> ## Documentation Index > Fetch the complete documentation index at: https://docs.kejue.co/llms.txt > Use this file to discover all available pages before exploring further. # Create Campaign > Create a new campaign. Supports all-in-one creation: pass ``contact_ids`` to add contacts and ``auto_start`` / ``scheduled_start_at`` to start the campaign in a single request. ## OpenAPI ````yaml /openapi.json post /campaigns openapi: 3.1.0 info: title: Kejue Public API description: >- The Kejue Public API lets you programmatically create calls, manage campaigns, and retrieve call results. ## Authentication All requests require an API key passed in the `X-API-Key` header: ``` X-API-Key: kej_live_... ``` API keys are scoped to a workspace. Create and manage keys from the Kejue dashboard under **Settings → API Keys**. ## Base URL ``` https://api.kejue.co/api/v1 ``` ## Rate Limits API requests are rate-limited per workspace. If you exceed the limit you'll receive a `429 Too Many Requests` response. ## Errors All error responses follow a consistent format: ```json { "error": "Human-readable message", "code": "ERROR_CODE", "details": {} } ``` version: 1.0.0 servers: - url: https://api.kejue.co/api/v1 description: Production security: - ApiKeyAuth: [] tags: - name: Agents description: >- Create and manage AI agents (personas). Each agent has a name, prompt, voice configuration, and optional tools. Agents are the core building block — attach voice configs, tools, and use them to make calls. - name: Calls description: >- Create outbound calls, retrieve call details and transcripts, and list calls with filtering. Each call is associated with a contact and optionally an agent and campaign. - name: Persona Calls description: >- Create calls with the full agent configuration pre-loaded. Applies the complete settings hierarchy (workspace → agent → campaign → overrides) with all agent tools, tags, scoring, and webhooks inherited automatically. - name: Contacts description: >- Create and manage contacts. Contacts represent the people your agents call. Each contact has a phone number, name, and optional metadata. Supports single creation, bulk import, and CSV upload. - name: Campaigns description: >- Create and manage calling campaigns. Campaigns let you batch-call a list of contacts with shared settings, scheduling, and retry logic. - name: Tools description: >- Create and manage custom HTTP tools that agents can invoke during calls. Tools let agents fetch data, trigger actions, or integrate with external systems mid-conversation. Each tool supports three parameter types: - **Dynamic parameters** — filled by the AI at runtime (visible to the AI) - **Static parameters** — fixed values sent with every invocation (hidden from the AI) - **System parameters** — values injected from the execution context at runtime, such as `call_id`, `contact_id`, or `workspace_id` (hidden from the AI) - name: Voices description: List available voices for use in agent voice configurations. - name: Phone Numbers description: List phone numbers available in your workspace for making outbound calls. - name: Webhooks description: >- Create and manage webhook subscriptions. Receive real-time notifications for call events (started, ended, etc.) at your specified URL. - name: Models description: List available AI models for use in agent voice configurations. paths: /campaigns: post: tags: - Campaigns summary: Create Campaign description: >- Create a new campaign. Supports all-in-one creation: pass ``contact_ids`` to add contacts and ``auto_start`` / ``scheduled_start_at`` to start the campaign in a single request. operationId: create_campaign_campaigns_post parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateCampaign' responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/CreateCampaignResponse' '400': description: >- The request was semantically invalid (e.g. mismatched IDs or inactive resource). content: application/json: example: error: persona_id does not match voice config's persona code: BAD_REQUEST details: {} schema: $ref: '#/components/schemas/ErrorResponse' '401': description: >- Missing or invalid API key. Pass a workspace API key in the `X-API-Key` header. content: application/json: example: error: Invalid or missing API key code: UNAUTHORIZED details: {} schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Persona not found in this workspace. content: application/json: example: error: Persona not found code: NOT_FOUND details: persona_id: non_existent_id schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Request body or query parameters failed validation. content: application/json: example: error: Validation failed code: VALIDATION_ERROR details: errors: - field: body.name message: Field required type: missing schema: $ref: '#/components/schemas/ErrorResponse' security: - ApiKeyAuth: [] components: schemas: CreateCampaign: properties: name: type: string maxLength: 255 minLength: 1 title: Name description: anyOf: - type: string - type: 'null' title: Description persona_id: anyOf: - type: string - type: 'null' title: Persona Id description: Persona to use voice_config_id: anyOf: - type: string - type: 'null' title: Voice Config Id description: Voice agent (infers persona) call_settings: anyOf: - $ref: '#/components/schemas/CallSettingsInput' - type: 'null' description: Call settings metadata: additionalProperties: true type: object title: Metadata contact_ids: anyOf: - items: type: string type: array maxItems: 10000 - type: 'null' title: Contact Ids description: Contact IDs to add (max 10,000) priority: type: integer maximum: 100 minimum: 1 title: Priority description: Queue priority default: 50 scheduled_start_at: anyOf: - type: string - type: 'null' title: Scheduled Start At description: Naive datetime 'YYYY-MM-DDTHH:MM' per contact timezone auto_start: type: boolean title: Auto Start description: Start immediately after adding contacts default: false type: object required: - name title: CreateCampaign description: Create a campaign (public API). CreateCampaignResponse: properties: id: type: string title: Id name: type: string title: Name status: type: string title: Status persona_id: anyOf: - type: string - type: 'null' title: Persona Id contacts_added: anyOf: - type: integer - type: 'null' title: Contacts Added scheduled_start_at: anyOf: - type: string - type: 'null' title: Scheduled Start At created_at: type: string format: date-time title: Created At type: object required: - id - name - status - created_at title: CreateCampaignResponse description: Response after creating a campaign via public API. ErrorResponse: properties: error: type: string title: Error code: type: string title: Code details: anyOf: - additionalProperties: true type: object - type: 'null' title: Details type: object required: - error - code title: ErrorResponse description: Standard error response. example: code: NOT_FOUND details: contact_id: '123' error: Contact not found CallSettingsInput: properties: call_start_hour: anyOf: - type: integer maximum: 23 minimum: 0 - type: 'null' title: Call Start Hour description: 'Earliest hour to call (0-23, contact timezone). Default: 9' call_start_minute: anyOf: - type: integer maximum: 59 minimum: 0 - type: 'null' title: Call Start Minute description: 'Earliest minute. Default: 0' call_end_hour: anyOf: - type: integer maximum: 23 minimum: 0 - type: 'null' title: Call End Hour description: 'Latest hour to call (0-23). Default: 18' call_end_minute: anyOf: - type: integer maximum: 59 minimum: 0 - type: 'null' title: Call End Minute description: 'Latest minute. Default: 0' allowed_days: anyOf: - items: type: integer type: array - type: 'null' title: Allowed Days description: >- Days of the week to call. 0=Monday, 6=Sunday. Default: [0,1,2,3,4] (Mon-Fri) auto_retry: anyOf: - type: boolean - type: 'null' title: Auto Retry description: 'Retry when contact doesn''t answer. Default: true' retry_schedule: anyOf: - items: type: integer type: array - type: 'null' title: Retry Schedule description: >- Minutes between retries, e.g. [60, 240] = retry after 1h, then 4h. Default: [60, 240] phone_assignment_mode: anyOf: - $ref: '#/components/schemas/PhoneAssignmentMode' - type: 'null' description: >- How to pick the origin phone number. 'local' = match contact's country, 'foreign' = use a different country, 'any' = no preference. Default: 'any' scoring_criteria: anyOf: - type: string - type: 'null' title: Scoring Criteria description: >- Free-text instructions for scoring the call 0-100. Example: 'Score based on buying intent and engagement level' tags: anyOf: - items: $ref: '#/components/schemas/TagDefinition' type: array - type: 'null' title: Tags description: Tag definitions -- AI applies matching tags after the call structured_data_schema: anyOf: - items: $ref: '#/components/schemas/StructuredDataField' type: array - type: 'null' title: Structured Data Schema description: Fields to extract from the conversation after the call server_url: anyOf: - type: string - type: 'null' title: Server Url description: URL to POST call events to (simple inline webhook) server_secret: anyOf: - type: string - type: 'null' title: Server Secret description: HMAC-SHA256 signing secret for server_url type: object title: CallSettingsInput description: >- Unified call settings -- controls call window, retry, scoring, tags, and post-call behavior. Can be set at agent level or campaign level. Null fields inherit from the parent level. Hierarchy (lowest -> highest priority): System Defaults -> Workspace -> Agent -> Campaign -> API Override. example: allowed_days: - 0 - 1 - 2 - 3 - 4 auto_retry: true call_end_hour: 17 call_start_hour: 9 phone_assignment_mode: local retry_schedule: - 60 - 240 scoring_criteria: Score 0-100 based on buying intent structured_data_schema: - description: Stated budget range key: budget - description: Decision timeline key: timeline tags: - description: Contact expressed buying interest name: Interested - description: Contact requested a follow-up call name: Follow-up PhoneAssignmentMode: type: string enum: - local - foreign - any title: PhoneAssignmentMode description: How to assign the origin phone number. TagDefinition: properties: name: type: string title: Name description: Tag label, e.g. 'Interested' description: type: string title: Description description: When to apply this tag -- the AI uses this to decide type: object required: - name - description title: TagDefinition description: A tag that can be applied to a call based on conversation content. StructuredDataField: properties: key: type: string title: Key description: Output field key, e.g. 'budget' description: type: string title: Description description: What to extract from the conversation type: object required: - key - description title: StructuredDataField description: A field to extract from the conversation after the call. securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: Workspace API key (e.g. `kej_live_...`) ````