> ## Documentation Index > Fetch the complete documentation index at: https://docs.pineyard.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a new agent > **API keys:** knowledge documents listed in `abilities` are attached only if the key has `knowledge.edit`. Custom functions are never attached by a key. Skipped items are reported in `warnings` (`knowledge_docs_skipped`, `function_assign_skipped`); the agent is still created. **Required scope:** `agents.edit` ## OpenAPI ````yaml /api-reference/openapi.json post /agents openapi: 3.0.3 info: title: Pineyard API version: 1.0.0 description: >- Programmatic access to agents, campaigns, calls, phone numbers, WhatsApp and results in your Pineyard workspace. servers: - url: https://api.pineyard.ai description: Production security: - bearerAuth: [] paths: /agents: post: summary: Create a new agent description: >- **API keys:** knowledge documents listed in `abilities` are attached only if the key has `knowledge.edit`. Custom functions are never attached by a key. Skipped items are reported in `warnings` (`knowledge_docs_skipped`, `function_assign_skipped`); the agent is still created. requestBody: content: application/json: schema: type: object properties: name: type: string minLength: 1 maxLength: 100 prompt: type: string maxLength: 128000 greeting: type: string maxLength: 2000 voice: type: string minLength: 1 preCallVariables: type: array items: type: string pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$ maxItems: 100 extractionConfig: type: object properties: prompt: type: string minLength: 1 maxLength: 4000 keys: type: array items: type: object properties: name: type: string minLength: 1 maxLength: 64 pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$ type: type: string enum: - string - number - integer - boolean - array - date - datetime description: type: string minLength: 1 maxLength: 500 required: - name - type - description minItems: 1 maxItems: 64 includeToolLogs: type: boolean default: false required: - prompt - keys agentType: type: string enum: - OUTBOUND - INBOUND enableRecording: type: boolean endCallEnabled: type: boolean endCallMessage: type: string maxLength: 500 endCallTriggers: type: array items: type: string enum: - CALLER_GOODBYE - GOAL_COMPLETED - IDLE - REMOVE_FROM_LIST maxItems: 4 maxCallDurationSecs: type: integer minimum: 60 maximum: 3600 backgroundAudioId: type: string nullable: true backgroundAudioVolume: type: number nullable: true minimum: 0 maximum: 1 voicemailDetectionEnabled: type: boolean voicemailMessage: type: string nullable: true maxLength: 500 screenerHandlingEnabled: type: boolean transferEnabled: type: boolean transferNumber: type: string maxLength: 32 pattern: ^\+\d{8,15}$ transferMessage: type: string maxLength: 500 transferTriggers: type: array items: type: string enum: - CALLER_ASKS_HUMAN - FRUSTRATED - ASKS_MANAGER - UNKNOWN_QUESTION - BILLING studioConfig: type: object properties: agentName: type: string minLength: 1 maxLength: 100 industry: type: string maxLength: 100 designation: type: string maxLength: 100 companyName: type: string minLength: 1 maxLength: 120 companyDescription: type: string maxLength: 4000 languages: type: array items: type: string minLength: 1 maxLength: 40 minItems: 1 maxItems: 24 primaryLanguage: type: string minLength: 1 maxLength: 40 gender: type: string enum: - female - male - neutral tone: type: string enum: - warm_professional - formal - casual - assertive - empathetic goal: type: string minLength: 1 maxLength: 2000 briefText: type: string maxLength: 8000 welcomeMessage: type: string maxLength: 2000 guardrails: type: array items: type: string enum: - no_fabrication - no_scope_creep - no_ai_disclosure - no_medical_legal_advice - no_pressure_selling - data_privacy - script_fidelity maxItems: 10 default: [] flowSteps: type: array items: type: object properties: id: type: string minLength: 1 maxLength: 64 title: type: string minLength: 1 maxLength: 200 detail: type: string maxLength: 2000 required: - id - title maxItems: 30 flowGraph: type: object properties: nodes: type: array items: type: object properties: id: type: string minLength: 1 maxLength: 64 type: type: string enum: - step - branch - end title: type: string minLength: 1 maxLength: 200 detail: type: string maxLength: 2000 position: type: object properties: x: type: number 'y': type: number required: - x - 'y' required: - id - type - title maxItems: 40 edges: type: array items: type: object properties: id: type: string minLength: 1 maxLength: 64 source: type: string minLength: 1 maxLength: 64 target: type: string minLength: 1 maxLength: 64 condition: type: string maxLength: 200 required: - id - source - target maxItems: 80 required: - nodes - edges faqs: type: array items: type: object properties: question: type: string minLength: 1 maxLength: 500 answer: type: string minLength: 1 maxLength: 2000 required: - question - answer maxItems: 30 closingBehavior: type: string enum: - confirm_and_end - transfer - callback - custom abilities: type: object properties: transfer: type: object properties: number: type: string maxLength: 32 pattern: ^\+\d{8,15}$ triggers: type: array items: type: string enum: - CALLER_ASKS_HUMAN - FRUSTRATED - ASKS_MANAGER - UNKNOWN_QUESTION - BILLING maxItems: 5 required: - number booking: type: object properties: types: type: array items: type: string enum: - site_visit - online_meet - phone_callback minItems: 1 maxItems: 3 required: - types callback: type: boolean whatsapp: type: object properties: collectionIds: type: array items: type: string minLength: 1 minItems: 0 maxItems: 20 templateIds: type: array items: type: string minLength: 1 minItems: 0 maxItems: 20 required: - collectionIds knowledgeDocIds: type: array items: type: string minLength: 1 maxItems: 20 functionIds: type: array items: type: string minLength: 1 maxItems: 20 languageSwitching: type: string enum: - fast - balanced - strict keyTerms: type: array items: type: string minLength: 1 maxLength: 40 maxItems: 40 sampleDialogue: type: string maxLength: 6000 promptSpec: anyOf: - type: number enum: - 1 - type: number enum: - 2 overrides: type: object properties: namesPolicy: type: string enum: - use_name - no_names identityConfirm: type: string enum: - by_name - by_enquiry silenceHandling: type: string enum: - ask - reengage endCallEtiquette: type: string enum: - close_only - final_question mixRatio: type: string enum: - balanced - english_leaning - hindi_leaning required: - agentName - companyName - languages - primaryLanguage - gender - tone - goal - flowSteps - faqs abilities: type: object properties: transfer: type: object properties: number: type: string maxLength: 32 pattern: ^\+\d{8,15}$ triggers: type: array items: type: string enum: - CALLER_ASKS_HUMAN - FRUSTRATED - ASKS_MANAGER - UNKNOWN_QUESTION - BILLING maxItems: 5 required: - number booking: type: object properties: types: type: array items: type: string enum: - site_visit - online_meet - phone_callback minItems: 1 maxItems: 3 required: - types callback: type: boolean whatsapp: type: object properties: collectionIds: type: array items: type: string minLength: 1 minItems: 0 maxItems: 20 templateIds: type: array items: type: string minLength: 1 minItems: 0 maxItems: 20 required: - collectionIds knowledgeDocIds: type: array items: type: string minLength: 1 maxItems: 20 functionIds: type: array items: type: string minLength: 1 maxItems: 20 required: - name - voice responses: '201': description: Created content: application/json: schema: type: object properties: id: type: string name: type: string prompt: type: string greeting: type: string nullable: true voice: type: string status: type: string preCallVariables: type: array nullable: true items: type: string variables: type: array items: type: string systemVariables: type: array items: type: string extractionConfig: type: object nullable: true properties: prompt: type: string minLength: 1 maxLength: 4000 keys: type: array items: type: object properties: name: type: string minLength: 1 maxLength: 64 pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$ type: type: string enum: - string - number - integer - boolean - array - date - datetime description: type: string minLength: 1 maxLength: 500 required: - name - type - description minItems: 1 maxItems: 64 includeToolLogs: type: boolean default: false required: - prompt - keys agentType: type: string enableRecording: type: boolean endCallEnabled: type: boolean endCallMessage: type: string nullable: true endCallTriggers: type: array nullable: true items: type: string maxCallDurationSecs: type: number nullable: true backgroundAudioId: type: string nullable: true backgroundAudioVolume: type: number nullable: true voicemailDetectionEnabled: type: boolean voicemailMessage: type: string nullable: true screenerHandlingEnabled: type: boolean transferEnabled: type: boolean transferNumber: type: string nullable: true transferMessage: type: string nullable: true transferTriggers: type: array nullable: true items: type: string language: type: string studioConfig: type: object nullable: true properties: agentName: type: string minLength: 1 maxLength: 100 industry: type: string maxLength: 100 designation: type: string maxLength: 100 companyName: type: string minLength: 1 maxLength: 120 companyDescription: type: string maxLength: 4000 languages: type: array items: type: string minLength: 1 maxLength: 40 minItems: 1 maxItems: 24 primaryLanguage: type: string minLength: 1 maxLength: 40 gender: type: string enum: - female - male - neutral tone: type: string enum: - warm_professional - formal - casual - assertive - empathetic goal: type: string minLength: 1 maxLength: 2000 briefText: type: string maxLength: 8000 welcomeMessage: type: string maxLength: 2000 guardrails: type: array items: type: string enum: - no_fabrication - no_scope_creep - no_ai_disclosure - no_medical_legal_advice - no_pressure_selling - data_privacy - script_fidelity maxItems: 10 default: [] flowSteps: type: array items: type: object properties: id: type: string minLength: 1 maxLength: 64 title: type: string minLength: 1 maxLength: 200 detail: type: string maxLength: 2000 required: - id - title maxItems: 30 flowGraph: type: object properties: nodes: type: array items: type: object properties: id: type: string minLength: 1 maxLength: 64 type: type: string enum: - step - branch - end title: type: string minLength: 1 maxLength: 200 detail: type: string maxLength: 2000 position: type: object properties: x: type: number 'y': type: number required: - x - 'y' required: - id - type - title maxItems: 40 edges: type: array items: type: object properties: id: type: string minLength: 1 maxLength: 64 source: type: string minLength: 1 maxLength: 64 target: type: string minLength: 1 maxLength: 64 condition: type: string maxLength: 200 required: - id - source - target maxItems: 80 required: - nodes - edges faqs: type: array items: type: object properties: question: type: string minLength: 1 maxLength: 500 answer: type: string minLength: 1 maxLength: 2000 required: - question - answer maxItems: 30 closingBehavior: type: string enum: - confirm_and_end - transfer - callback - custom abilities: type: object properties: transfer: type: object properties: number: type: string maxLength: 32 pattern: ^\+\d{8,15}$ triggers: type: array items: type: string enum: - CALLER_ASKS_HUMAN - FRUSTRATED - ASKS_MANAGER - UNKNOWN_QUESTION - BILLING maxItems: 5 required: - number booking: type: object properties: types: type: array items: type: string enum: - site_visit - online_meet - phone_callback minItems: 1 maxItems: 3 required: - types callback: type: boolean whatsapp: type: object properties: collectionIds: type: array items: type: string minLength: 1 minItems: 0 maxItems: 20 templateIds: type: array items: type: string minLength: 1 minItems: 0 maxItems: 20 required: - collectionIds knowledgeDocIds: type: array items: type: string minLength: 1 maxItems: 20 functionIds: type: array items: type: string minLength: 1 maxItems: 20 languageSwitching: type: string enum: - fast - balanced - strict keyTerms: type: array items: type: string minLength: 1 maxLength: 40 maxItems: 40 sampleDialogue: type: string maxLength: 6000 promptSpec: anyOf: - type: number enum: - 1 - type: number enum: - 2 overrides: type: object properties: namesPolicy: type: string enum: - use_name - no_names identityConfirm: type: string enum: - by_name - by_enquiry silenceHandling: type: string enum: - ask - reengage endCallEtiquette: type: string enum: - close_only - final_question mixRatio: type: string enum: - balanced - english_leaning - hindi_leaning required: - agentName - companyName - languages - primaryLanguage - gender - tone - goal - flowSteps - faqs abilities: type: object nullable: true properties: transfer: type: object properties: number: type: string maxLength: 32 pattern: ^\+\d{8,15}$ triggers: type: array items: type: string enum: - CALLER_ASKS_HUMAN - FRUSTRATED - ASKS_MANAGER - UNKNOWN_QUESTION - BILLING maxItems: 5 required: - number booking: type: object properties: types: type: array items: type: string enum: - site_visit - online_meet - phone_callback minItems: 1 maxItems: 3 required: - types callback: type: boolean whatsapp: type: object properties: collectionIds: type: array items: type: string minLength: 1 minItems: 0 maxItems: 20 templateIds: type: array items: type: string minLength: 1 minItems: 0 maxItems: 20 required: - collectionIds knowledgeDocIds: type: array items: type: string minLength: 1 maxItems: 20 functionIds: type: array items: type: string minLength: 1 maxItems: 20 promptEditedManually: type: boolean createdAt: type: string updatedAt: type: string warnings: type: array items: type: object properties: code: type: string message: type: string required: - code - message required: - id - name - prompt - greeting - voice - status - preCallVariables - variables - systemVariables - extractionConfig - agentType - enableRecording - endCallEnabled - endCallMessage - endCallTriggers - maxCallDurationSecs - backgroundAudioId - backgroundAudioVolume - voicemailDetectionEnabled - voicemailMessage - screenerHandlingEnabled - transferEnabled - transferNumber - transferMessage - transferTriggers - language - studioConfig - abilities - promptEditedManually - createdAt - updatedAt '400': description: >- - `internal_error`: An unexpected error. A `400` with this code usually means the body is not valid JSON; a `413` means the body is larger than 1 MB. - `invalid_body`: The request body (or query) failed validation. Details are in `issues` (or `detail`). `422` on `POST /v1/campaigns/{campaignId}/leads`. - `invalid_transfer_number`: Transfer number is not E.164. - `prompt_required`: Agent create has no prompt after assembly. - `transfer_number_required`: Transfer enabled without a number. '401': description: >- - `invalid_api_key`: The API key is unknown, revoked or expired, or its workspace was deleted. - `unauthorized`: No `Authorization: Bearer` header, or an empty token. '403': description: >- - `api_key_not_scoped`: A key issued without scopes was used outside `/v1`. - `api_key_owner_inactive`: The member the key acts for was removed or suspended. - `forbidden`: The key lacks the permission named in `requiredPermission`, or the resource belongs to another workspace. - `workspace_pending_approval`: The workspace has not been approved yet. - `workspace_suspended`: The workspace is suspended. '404': description: >- - `background_audio_not_found`: Background audio id not owned by this workspace or not available. '409': description: >- - `name_taken`: An agent, campaign or campaign type with that name already exists (unique constraint). '413': description: >- - `internal_error`: An unexpected error. A `400` with this code usually means the body is not valid JSON; a `413` means the body is larger than 1 MB. '429': description: '- `rate_limited`: Too many requests.' '500': description: >- - `internal_error`: An unexpected error. A `400` with this code usually means the body is not valid JSON; a `413` means the body is larger than 1 MB. '502': description: >- - `provider_error`: The calling service rejected the request (`upstreamStatus` 4xx) or was unavailable (5xx). '503': description: '- `database_unavailable`: The service is temporarily unavailable.' components: securitySchemes: bearerAuth: type: http scheme: bearer description: Your API key, e.g. `pk_live_xxxxxxxxxxxxxxxxxxxxxxxx`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.