> ## 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. # Create a custom agent > Creates a custom agent, as Create agent does on the Agents page, with the same validation; a model that is not available now is refused with 400. The agent starts with no schedule. The response carries its agentKey. A retry creates a second agent. 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 post /projects/{projectId}/agents 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: post: summary: Create a custom agent description: >- Creates a custom agent, as Create agent does on the Agents page, with the same validation; a model that is not available now is refused with 400. The agent starts with no schedule. The response carries its agentKey. A retry creates a second agent. 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: createCustomAgent parameters: - name: projectId in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CustomAgentInput' responses: '201': 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' '429': $ref: '#/components/responses/RateLimitExceededError' security: - bearerAuth: [] - oauthBearer: [] components: schemas: CustomAgentInput: type: object additionalProperties: false required: - displayName - description - instructions - modelId - quickActions - toolAllowlist properties: displayName: type: string minLength: 1 maxLength: 80 description: type: string minLength: 1 maxLength: 240 description: One sentence saying what the agent does. instructions: type: string minLength: 1 maxLength: 12000 description: What the agent does on every run. modelId: type: string minLength: 1 maxLength: 120 description: A model available now; others are refused with 400. quickActions: type: array minItems: 1 maxItems: 6 items: type: string minLength: 1 maxLength: 160 description: Suggested requests shown with the agent. toolAllowlist: type: array minItems: 1 uniqueItems: true items: type: string description: >- Tools the agent may use, including exactly one draft output: create_draft_action, create_draft_brief or create_report_artifact. 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' 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.