> ## Documentation Index > Fetch the complete documentation index at: https://docs.devtune.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update a custom agent > Changes a custom agent's name, description, instructions, model, quick actions or tools. Send only the fields to change; the result must still be a valid agent by the Agents page's rules. If the agent's model is no longer available, the request is refused with 400 and reason model_unavailable until you also send modelId with an available model. The schedule is kept, and runs already started keep the definition they started with. If the agent changes between DevTune reading it and saving your change, the request is refused with 409 and reason revision_changed, and nothing is saved; read the agent again and retry. Built-in agents cannot be edited (400); a custom agent outside this project returns 404. The OAuth member, or the member who created the API key, must belong to the project and hold the manage permission; otherwise 403. Requires the agents.write scope. ## OpenAPI ````yaml /openapi.json patch /projects/{projectId}/agents/{agentKey} openapi: 3.1.0 info: title: DevTune API version: 2.0.0 description: >- API for programmatic access to your AI visibility data, webhook subscriptions, and automation workflows. Use this API to integrate DevTune data into CI/CD pipelines, BI tools, AI agents, and operational systems. servers: - url: https://devtune.ai/api/v2 description: Production security: - bearerAuth: [] paths: /projects/{projectId}/agents/{agentKey}: patch: summary: Update a custom agent description: >- Changes a custom agent's name, description, instructions, model, quick actions or tools. Send only the fields to change; the result must still be a valid agent by the Agents page's rules. If the agent's model is no longer available, the request is refused with 400 and reason model_unavailable until you also send modelId with an available model. The schedule is kept, and runs already started keep the definition they started with. If the agent changes between DevTune reading it and saving your change, the request is refused with 409 and reason revision_changed, and nothing is saved; read the agent again and retry. Built-in agents cannot be edited (400); a custom agent outside this project returns 404. The OAuth member, or the member who created the API key, must belong to the project and hold the manage permission; otherwise 403. Requires the agents.write scope. operationId: updateCustomAgent parameters: - name: projectId in: path required: true schema: type: string format: uuid - name: agentKey in: path required: true description: A custom agent key from listManagedAgents. schema: type: string requestBody: required: true content: application/json: schema: type: object additionalProperties: false minProperties: 1 properties: displayName: type: string minLength: 1 maxLength: 80 description: type: string minLength: 1 maxLength: 240 instructions: type: string minLength: 1 maxLength: 12000 modelId: type: string minLength: 1 maxLength: 120 quickActions: type: array minItems: 1 maxItems: 6 items: type: string minLength: 1 maxLength: 160 toolAllowlist: type: array minItems: 1 uniqueItems: true items: type: string responses: '200': description: The custom agent content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/CustomAgentWrite' meta: $ref: '#/components/schemas/Meta' required: - data - meta '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/NotFoundError' '409': $ref: '#/components/responses/ConflictError' '429': $ref: '#/components/responses/RateLimitExceededError' security: - bearerAuth: [] - oauthBearer: [] components: schemas: CustomAgentWrite: type: object additionalProperties: false required: - agent properties: agent: $ref: '#/components/schemas/CustomAgent' Meta: type: object properties: timestamp: type: string format: date-time projectId: type: string format: uuid CustomAgent: type: object additionalProperties: false required: - agentKey - displayName - description - instructions - modelId - quickActions - toolAllowlist - outputArtifactType - workflowKey - isCustom - scheduling properties: agentKey: type: string displayName: type: string description: type: string instructions: type: string modelId: type: string quickActions: type: array items: type: string toolAllowlist: type: array items: type: string description: >- The tools the agent uses, including library search, which every agent gets. outputArtifactType: type: string enum: - action - brief - report workflowKey: type: string isCustom: type: boolean enum: - true scheduling: $ref: '#/components/schemas/AgentScheduleState' Error: type: object properties: error: type: string message: type: string reason: type: string description: >- Why the request was refused, for an error with more than one cause, such as a refused content-draft start. details: type: object additionalProperties: true description: >- Machine-readable facts about the refusal, such as shortfall_credits when an Agent Picks start is refused for insufficient_credits. status: type: integer required: - error - message - status AgentScheduleState: type: object additionalProperties: false required: - autonomyLevel - schedule - modelId - scheduledAt properties: autonomyLevel: type: string enum: - manual - scheduled description: scheduled when the schedule is on; manual when it is off. schedule: nullable: true allOf: - $ref: '#/components/schemas/AgentSchedule' modelId: type: string nullable: true description: The model scheduled runs use. scheduledAt: type: string format: date-time nullable: true description: When the schedule was last turned on or changed. AgentSchedule: description: >- When scheduled runs start: daily, weekly on dayOfWeek, or monthly on dayOfMonth, at time in timezone. oneOf: - $ref: '#/components/schemas/AgentScheduleDaily' - $ref: '#/components/schemas/AgentScheduleWeekly' - $ref: '#/components/schemas/AgentScheduleMonthly' AgentScheduleDaily: type: object additionalProperties: false required: - cadence - time - timezone properties: cadence: type: string enum: - daily time: type: string pattern: ^([01]\d|2[0-3]):[0-5]\d$ description: Run time as 24-hour HH:mm. timezone: type: string description: IANA timezone, such as Europe/London. modelId: type: string minLength: 1 description: >- Optional. The modelId sent beside the schedule is the one scheduled runs use. AgentScheduleWeekly: type: object additionalProperties: false required: - cadence - dayOfWeek - time - timezone properties: cadence: type: string enum: - weekly dayOfWeek: type: integer minimum: 0 maximum: 6 description: 0 (Sunday) to 6 (Saturday). time: type: string pattern: ^([01]\d|2[0-3]):[0-5]\d$ description: Run time as 24-hour HH:mm. timezone: type: string description: IANA timezone, such as Europe/London. modelId: type: string minLength: 1 description: >- Optional. The modelId sent beside the schedule is the one scheduled runs use. AgentScheduleMonthly: type: object additionalProperties: false required: - cadence - dayOfMonth - time - timezone properties: cadence: type: string enum: - monthly dayOfMonth: type: integer minimum: 1 maximum: 28 time: type: string pattern: ^([01]\d|2[0-3]):[0-5]\d$ description: Run time as 24-hour HH:mm. timezone: type: string description: IANA timezone, such as Europe/London. modelId: type: string minLength: 1 description: >- Optional. The modelId sent beside the schedule is the one scheduled runs use. responses: BadRequestError: description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' UnauthorizedError: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' ForbiddenError: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' NotFoundError: description: Not found content: application/json: schema: $ref: '#/components/schemas/Error' ConflictError: description: Request conflicts with current resource state content: application/json: schema: $ref: '#/components/schemas/Error' RateLimitExceededError: description: Rate limit exceeded headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/Error' headers: X-RateLimit-Limit: description: Maximum requests per window schema: type: integer X-RateLimit-Remaining: description: Requests remaining in current window schema: type: integer X-RateLimit-Reset: description: Unix timestamp when the window resets schema: type: integer securitySchemes: bearerAuth: type: http scheme: bearer description: >- API key with dtk_live_ prefix. Obtain it from API Keys in the account sidebar. New keys start with all supported scopes selected for the chosen project, and you can narrow them to specific read/write scopes as needed. oauthBearer: type: http scheme: bearer description: >- Project-granted OAuth access token from the authorization server advertised at /.well-known/oauth-protected-resource/api/v2. Uses the same browser consent and current project permissions as MCP. Only operations explicitly listing oauthBearer accept these tokens. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.