> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sendora.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload an image

> Upload an image as multipart form data (`file`, and `kind` for avatars) and apply it right away.
Returns the updated agent or widget. This operation can change workspace data or trigger an external side effect; review the request before sending it and do not retry blindly after a timeout.



## OpenAPI

````yaml /openapi.json post /api/v1/public/files
openapi: 3.1.0
info:
  description: >-
    Customer-facing API for managing outreach, leads, conversations, voice
    agents, knowledge bases, analytics, and webhooks.
  title: Sendora Public API
  version: 1.0.0
servers:
  - description: Production
    url: https://api.sendora.ai
security: []
tags:
  - description: Leads, lead lists, importing, enriching and finding new prospects.
    name: Leads
  - description: Build, run and measure outreach, and enroll leads.
    name: Campaigns
  - description: Read and send messages, and manage who must not be contacted.
    name: Conversations
  - description: >-
      Voice and chat agents, their tools, knowledge bases, voices and website
      widgets.
    name: Agents
  - description: >-
      Start calls, and manage phone numbers, SMS registration, sending accounts
      and email domains.
    name: Calls and numbers
  - description: Webhooks, jobs, analytics and the Copilot assistant.
    name: Platform
  - description: Manage client workspaces, plans and branding.
    name: Agency
paths:
  /api/v1/public/files:
    post:
      tags:
        - Agents
      summary: Upload an image
      description: >-
        Upload an image as multipart form data (`file`, and `kind` for avatars)
        and apply it right away.

        Returns the updated agent or widget. This operation can change workspace
        data or trigger an external side effect; review the request before
        sending it and do not retry blindly after a timeout.
      operationId: upload_image_api_v1_public_files_post
      parameters:
        - description: What the image is for.
          in: query
          name: purpose
          required: true
          schema:
            description: What the image is for.
            enum:
              - agent_avatar
              - widget_avatar
              - widget_launcher
            title: Purpose
            type: string
        - description: >-
            The voice agent's id: the `id` from List or get agents. It is also
            the last part of that page's address in the app.
          in: query
          name: agent_id
          required: true
          schema:
            description: The agent the image belongs to.
            title: Agent Id
            type: string
        - description: >-
            The widget's id: the `id` from List or read tools and widgets (type
            widget) for this agent.
          in: query
          name: widget_id
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Needed for widget_avatar and widget_launcher.
            title: Widget Id
        - in: header
          name: X-API-Key
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Api-Key
        - in: header
          name: Authorization
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Authorization
      responses:
        '200':
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/PublicVoiceAgentOut'
                  - $ref: '#/components/schemas/WidgetOut'
                title: Response Upload Image Api V1 Public Files Post
          description: Successful Response
        '401':
          description: The X-API-Key header is missing, invalid, expired, or revoked.
        '402':
          description: >-
            The workspace is suspended for billing, or the request would exceed
            a plan or usage limit.
        '403':
          description: >-
            The key is valid but lacks the required scope, or the workspace has
            no active plan, lacks the entitlement, or has this feature turned
            off or view-only.
        '410':
          description: The workspace behind this key has been deleted.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
        '500':
          description: >-
            An unexpected Sendora error occurred. Retry only if the operation is
            safe to repeat.
        '503':
          description: >-
            An entitlement or billing check is temporarily unavailable. Retry
            after the Retry-After interval.
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - label: cURL
          lang: bash
          source: >-
            curl -X POST 'https://api.sendora.ai/api/v1/public/files' -H
            "X-API-Key: $SENDORA_API_KEY"
        - label: Python
          lang: python
          source: |-
            import requests

            url = 'https://api.sendora.ai/api/v1/public/files'
            headers = {'X-API-Key': '$SENDORA_API_KEY'}
            response = requests.post(url, headers=headers)
            response.raise_for_status()
            print(response.json())
        - label: JavaScript
          lang: javascript
          source: >-
            const response = await
            fetch("https://api.sendora.ai/api/v1/public/files", {
              method: "POST",
              headers: { 'X-API-Key': process.env.SENDORA_API_KEY },
            });

            if (!response.ok) throw new Error(await response.text());

            console.log(await response.json());
        - label: Go
          lang: go
          source: >-
            req, err := http.NewRequest("POST",
            "https://api.sendora.ai/api/v1/public/files", nil)

            if err != nil { log.Fatal(err) }

            req.Header.Set("X-API-Key", os.Getenv("SENDORA_API_KEY"))

            resp, err := http.DefaultClient.Do(req)

            if err != nil { log.Fatal(err) }

            defer resp.Body.Close()
components:
  schemas:
    PublicVoiceAgentOut:
      description: >-
        Deliberately minimal public representation of a voice agent.


        The authenticated operator API returns the full configuration, but
        public

        API keys must not receive system prompts, tool definitions, tenant IDs,
        or

        connected service resource identifiers as an incidental side effect of
        listing an

        agent. Configuration is accepted on write requests but is never echoed.
      properties:
        created_at:
          description: Created at returned by the Sendora API.
          format: date-time
          title: Created At
          type: string
        direction:
          default: outbound
          description: Direction returned by the Sendora API.
          title: Direction
          type: string
        display_name:
          anyOf:
            - type: string
            - type: 'null'
          description: Display name returned by the Sendora API.
          title: Display Name
        first_message:
          default: ''
          description: First message returned by the Sendora API.
          title: First Message
          type: string
        id:
          description: The voice agent's id. Pass it to any endpoint that takes `agent_id`.
          title: Id
          type: string
        is_active:
          default: false
          description: Is active returned by the Sendora API.
          title: Is Active
          type: boolean
        name:
          description: Name returned by the Sendora API.
          title: Name
          type: string
        ready:
          default: false
          description: Ready returned by the Sendora API.
          title: Ready
          type: boolean
        updated_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: Updated at returned by the Sendora API.
          title: Updated At
      required:
        - id
        - name
        - created_at
      title: PublicVoiceAgentOut
      type: object
    WidgetOut:
      properties:
        agent_id:
          description: 'A voice agent''s id: the `id` from List or get agents.'
          title: Agent Id
          type: string
        allowed_origins:
          description: Allowed origins returned by the Sendora API.
          items:
            type: string
          title: Allowed Origins
          type: array
        avatar_url:
          anyOf:
            - type: string
            - type: 'null'
          description: Avatar url returned by the Sendora API.
          title: Avatar Url
        avatar_video_live_url:
          anyOf:
            - type: string
            - type: 'null'
          description: Avatar video live url returned by the Sendora API.
          title: Avatar Video Live Url
        avatar_video_pre_call_url:
          anyOf:
            - type: string
            - type: 'null'
          description: Avatar video pre call url returned by the Sendora API.
          title: Avatar Video Pre Call Url
        avatar_video_url:
          anyOf:
            - type: string
            - type: 'null'
          description: Avatar video url returned by the Sendora API.
          title: Avatar Video Url
        consent_text:
          description: Consent text returned by the Sendora API.
          title: Consent Text
          type: string
        created_at:
          description: Created at returned by the Sendora API.
          title: Created At
          type: string
        daily_call_cap:
          anyOf:
            - type: integer
            - type: 'null'
          description: Daily call cap returned by the Sendora API.
          title: Daily Call Cap
        display_mode:
          default: conversation
          description: Display mode returned by the Sendora API.
          enum:
            - conversation
            - compact
            - launcher
          title: Display Mode
          type: string
        display_name:
          anyOf:
            - type: string
            - type: 'null'
          description: Display name returned by the Sendora API.
          title: Display Name
        greeting_text:
          description: Greeting text returned by the Sendora API.
          title: Greeting Text
          type: string
        id:
          description: The widget's id. Pass it to any endpoint that takes `widget_id`.
          title: Id
          type: string
        is_active:
          description: Is active returned by the Sendora API.
          title: Is Active
          type: boolean
        launcher_icon:
          default: iridescent
          description: Launcher icon returned by the Sendora API.
          title: Launcher Icon
          type: string
        launcher_media_type:
          anyOf:
            - enum:
                - image
                - video
              type: string
            - type: 'null'
          description: Launcher media type returned by the Sendora API.
          title: Launcher Media Type
        launcher_media_url:
          anyOf:
            - type: string
            - type: 'null'
          description: Launcher media url returned by the Sendora API.
          title: Launcher Media Url
        max_concurrent_calls:
          description: Max concurrent calls returned by the Sendora API.
          title: Max Concurrent Calls
          type: integer
        name:
          description: Name returned by the Sendora API.
          title: Name
          type: string
        position:
          description: Position returned by the Sendora API.
          title: Position
          type: string
        pre_call_form:
          description: Pre call form returned by the Sendora API.
          items:
            type: object
          title: Pre Call Form
          type: array
        require_consent:
          description: Require consent returned by the Sendora API.
          title: Require Consent
          type: boolean
        settings:
          $ref: >-
            #/components/schemas/api__v1__voice_widgets__schemas__WidgetEditorSettings
          description: Settings returned by the Sendora API.
        show_transcript:
          description: Show transcript returned by the Sendora API.
          title: Show Transcript
          type: boolean
        target_list_id:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The lead list new leads from this widget are saved to: an `id` from
            List or read lead collections (type list).
          title: Target List Id
        theme:
          description: Theme returned by the Sendora API.
          title: Theme
          type: object
        updated_at:
          description: Updated at returned by the Sendora API.
          title: Updated At
          type: string
      required:
        - id
        - agent_id
        - name
        - is_active
        - position
        - theme
        - greeting_text
        - consent_text
        - require_consent
        - pre_call_form
        - show_transcript
        - allowed_origins
        - max_concurrent_calls
        - created_at
        - updated_at
      title: WidgetOut
      type: object
    HTTPValidationError:
      properties:
        detail:
          description: Detail returned by the Sendora API.
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      required: []
      title: HTTPValidationError
      type: object
    api__v1__voice_widgets__schemas__WidgetEditorSettings:
      description: >-
        Optional presentation and interaction settings owned by one widget.


        The top-level widget columns remain the compatibility contract; this

        object contains additive editor controls so new UI choices do not
        require

        a migration for every small visual preference.
      properties:
        accent_color:
          default: '#18181b'
          description: Accent color returned by the Sendora API.
          maxLength: 32
          title: Accent Color
          type: string
        auto_create_contact:
          default: true
          description: Auto create contact returned by the Sendora API.
          title: Auto Create Contact
          type: boolean
        auto_open:
          default: never
          description: Auto open returned by the Sendora API.
          enum:
            - never
            - delay
            - scroll
            - exit-intent
          title: Auto Open
          type: string
        auto_open_delay_seconds:
          default: 5
          description: Auto open delay seconds returned by the Sendora API.
          maximum: 120
          minimum: 1
          title: Auto Open Delay Seconds
          type: integer
        capture_device:
          default: false
          description: Capture device returned by the Sendora API.
          title: Capture Device
          type: boolean
        capture_referrer:
          default: true
          description: Capture referrer returned by the Sendora API.
          title: Capture Referrer
          type: boolean
        capture_timezone:
          default: true
          description: Capture timezone returned by the Sendora API.
          title: Capture Timezone
          type: boolean
        capture_utm:
          default: true
          description: Capture utm returned by the Sendora API.
          title: Capture Utm
          type: boolean
        close_behavior:
          default: manual
          description: Close behavior returned by the Sendora API.
          enum:
            - manual
            - outside-click
          title: Close Behavior
          type: string
        contact_match:
          default: email-or-phone
          description: Contact match returned by the Sendora API.
          enum:
            - email
            - phone
            - email-or-phone
          title: Contact Match
          type: string
        cta_label:
          default: Start call
          description: Cta label returned by the Sendora API.
          maxLength: 80
          title: Cta Label
          type: string
        font:
          default: system
          description: Font returned by the Sendora API.
          enum:
            - system
            - cal-sans
          title: Font
          type: string
        mobile_behavior:
          default: responsive
          description: Mobile behavior returned by the Sendora API.
          enum:
            - responsive
            - full-screen
            - launcher
          title: Mobile Behavior
          type: string
        primary_color:
          default: '#6366f1'
          description: Primary color returned by the Sendora API.
          maxLength: 32
          title: Primary Color
          type: string
        privacy_policy_url:
          anyOf:
            - maxLength: 500
              type: string
            - type: 'null'
          description: Privacy policy url returned by the Sendora API.
          title: Privacy Policy Url
        radius:
          default: rounded
          description: Radius returned by the Sendora API.
          enum:
            - subtle
            - rounded
            - pill
          title: Radius
          type: string
        separate_videos:
          default: false
          description: Separate videos returned by the Sendora API.
          title: Separate Videos
          type: boolean
        shadow:
          default: soft
          description: Shadow returned by the Sendora API.
          enum:
            - none
            - soft
            - elevated
          title: Shadow
          type: string
        show_end:
          default: true
          description: Show end returned by the Sendora API.
          title: Show End
          type: boolean
        show_mute:
          default: true
          description: Show mute returned by the Sendora API.
          title: Show Mute
          type: boolean
        show_status:
          default: true
          description: Show status returned by the Sendora API.
          title: Show Status
          type: boolean
        size:
          default: medium
          description: Size returned by the Sendora API.
          enum:
            - small
            - medium
            - large
          title: Size
          type: string
        terms_url:
          anyOf:
            - maxLength: 500
              type: string
            - type: 'null'
          description: Terms url returned by the Sendora API.
          title: Terms Url
        update_existing_contact:
          default: false
          description: Update existing contact returned by the Sendora API.
          title: Update Existing Contact
          type: boolean
      required: []
      title: WidgetEditorSettings
      type: object
    ValidationError:
      properties:
        loc:
          description: Loc returned by the Sendora API.
          items:
            anyOf:
              - type: string
              - type: integer
          title: Location
          type: array
        msg:
          description: Msg returned by the Sendora API.
          title: Message
          type: string
        type:
          description: Type returned by the Sendora API.
          title: Error Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationError
      type: object
  securitySchemes:
    ApiKeyAuth:
      description: Customer API key created in the Sendora dashboard.
      in: header
      name: X-API-Key
      type: apiKey

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.