> ## Documentation Index > Fetch the complete documentation index at: https://docs.brosbots.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Campaign > Create a new campaign ## OpenAPI ````yaml /api-reference/openapi.en.json post /api/v1/campaigns openapi: 3.1.0 info: title: Brosbots API description: > The public Brosbots REST API. Build and manage voice agents, run outbound campaigns, read calls and usage, and manage phone numbers, tools, knowledge bases and integrations. ## Authentication Every request must include your organization's API key in the `X-API-Key` header: ``` X-API-Key: bb_live_... ``` You create and revoke keys in the dashboard: click your account in the bottom-left corner of the sidebar, then **Brosbots API**. ## Base URL ``` https://app.brosbots.com/api/v1 ``` ## Conventions - Request and response bodies are JSON (`Content-Type: application/json`). - Timestamps are ISO 8601 with a timezone. - Lists are paginated with `page` / `limit` parameters; responses include `total_count` / `total_pages`. - Errors use standard HTTP status codes with a JSON body: `{"detail": "a human-readable reason"}`. - `{agent_id}` accepts the agent's public ID (`agent_...`) or its number. ## Limits There is no fixed per-key request-rate limit today. `429` comes from the calling endpoints (`POST /agents/{agent_id}/calls` and `POST /triggers/{trigger_id}/calls`) when every outbound channel is busy; its `Retry-After` header says how many seconds to wait. Handle `429` generally: wait as long as `Retry-After` says, or back off exponentially when it is absent. A request-rate limit may be introduced. version: 1.0.0 servers: [] security: - ApiKeyAuth: [] paths: /api/v1/campaigns: post: tags: - Campaigns summary: Create Campaign description: Create a new campaign operationId: post_campaigns parameters: - name: authorization in: header required: false schema: anyOf: - type: string - type: 'null' - name: X-API-Key in: header required: false schema: anyOf: - type: string - type: 'null' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateCampaignRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/CampaignResponse' '404': description: Not found '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: CreateCampaignRequest: properties: name: type: string maxLength: 255 minLength: 1 goal: anyOf: - type: string maxLength: 64 - type: 'null' workflow_id: type: integer source_type: type: string pattern: ^(google-sheet|csv|manual|calendar)$ source_id: type: string default: '' manual_contacts: anyOf: - items: $ref: '#/components/schemas/ManualContact' type: array - type: 'null' source_config: anyOf: - additionalProperties: true type: object - type: 'null' retry_config: anyOf: - $ref: '#/components/schemas/RetryConfig' - type: 'null' source_refresh_minutes: anyOf: - type: integer maximum: 10080 minimum: 5 - type: 'null' scheduled_start_at: anyOf: - type: string format: date-time - type: 'null' calling_window: anyOf: - $ref: '#/components/schemas/CallingWindowRequest' - type: 'null' type: object required: - name - workflow_id - source_type title: CreateCampaignRequest CampaignResponse: properties: id: type: integer name: type: string goal: anyOf: - type: string - type: 'null' workflow_id: type: integer workflow_name: type: string state: type: string source_type: type: string source_id: type: string source_config: anyOf: - additionalProperties: true type: object - type: 'null' source_refresh_minutes: anyOf: - type: integer - type: 'null' source_last_synced_at: anyOf: - type: string format: date-time - type: 'null' source_sync_error: anyOf: - type: string - type: 'null' scheduled_start_at: anyOf: - type: string format: date-time - type: 'null' calling_window: anyOf: - additionalProperties: true type: object - type: 'null' total_rows: anyOf: - type: integer - type: 'null' processed_rows: type: integer failed_rows: type: integer created_at: type: string format: date-time started_at: anyOf: - type: string format: date-time - type: 'null' completed_at: anyOf: - type: string format: date-time - type: 'null' type: object required: - id - name - workflow_id - workflow_name - state - source_type - source_id - total_rows - processed_rows - failed_rows - created_at - started_at - completed_at title: CampaignResponse HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array type: object title: HTTPValidationError ManualContact: properties: phone_number: type: string minLength: 1 first_name: type: string default: '' last_name: type: string default: '' type: object required: - phone_number title: ManualContact RetryConfig: properties: enabled: type: boolean default: true max_retries: type: integer maximum: 5 minimum: 0 default: 1 retry_delay_seconds: type: integer maximum: 86400 minimum: 60 default: 3600 retry_on_busy: type: boolean default: true retry_on_no_answer: type: boolean default: true retry_on_voicemail: type: boolean default: false smart_timing: type: boolean default: false type: object title: RetryConfig CallingWindowRequest: properties: timezone: type: string default: Europe/Warsaw days: items: type: integer type: array default: - 1 - 2 - 3 - 4 - 5 start: type: string default: '09:00' end: type: string default: '17:00' type: object title: CallingWindowRequest description: Hours a campaign may dial in, in the customer's own timezone. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array msg: type: string type: type: string type: object required: - loc - msg - type title: ValidationError securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: >- Your organization's API key (account in the bottom-left of the dashboard → Brosbots API). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.