> ## Documentation Index > Fetch the complete documentation index at: https://docs.tryvox.co/llms.txt > Use this file to discover all available pages before exploring further. # 위젯 목록 조회 > 인증된 조직의 위젯 목록을 조회합니다. `status=archived`를 지정하지 않으면 `archived` 위젯은 제외됩니다. `status`를 반복하면 여러 상태를 함께 조회합니다. ## OpenAPI ````yaml /api-reference/v3/openapi.json get /widgets openapi: 3.1.0 info: title: vox.ai API description: > vox.ai API v3 ### v3 공개 계약 규칙 - 인증은 `Authorization: Bearer ` 헤더를 사용합니다. 조직 API 키를 Bearer 토큰으로 전달합니다. - 요청과 응답 필드는 기본적으로 `snake_case`를 사용합니다. - `agent.data`는 에이전트 레지스트리와 호환되어야 하므로 `callSettings`, `toolIds`, `builtInTools`, `presetDynamicVariables` 같은 camelCase 필드를 유지합니다. - `_at`으로 끝나는 타임스탬프는 unix milliseconds입니다. 일부 입력값은 호환성을 위해 10~11자리 unix seconds도 허용하고 milliseconds로 정규화합니다. - 캠페인 통화 가능 시간은 분 단위 정수(`start_min` / `end_min`)를 사용합니다. 알림 스케줄은 `HH:MM` 문자열(`start_time` / `end_time`)을 사용합니다. - 응답 객체 자신의 식별자는 `id`입니다. 다른 리소스를 참조하는 필드와 path parameter는 `agent_id`, `call_id`, `telephone_line_id`처럼 명시적인 이름을 사용합니다. - 실패 응답은 `{ "error": { "code", "message", "details" } }` 형태입니다. 가능한 경우 `details.field`, `details.reason`, `details.allowed_values`를 함께 제공합니다. version: 3.0.0 servers: - url: https://client-api.tryvox.co/v3 description: 운영 security: [] paths: /widgets: get: tags: - Widgets summary: 위젯 목록 조회 description: >- 인증된 조직의 위젯 목록을 조회합니다. `status=archived`를 지정하지 않으면 `archived` 위젯은 제외됩니다. `status`를 반복하면 여러 상태를 함께 조회합니다. operationId: listWidgets parameters: - name: status in: query required: false schema: anyOf: - type: array items: enum: - draft - published - archived type: string - type: 'null' description: >- 위젯 상태 필터입니다. 허용값은 `draft`, `published`, `archived`이며 여러 상태를 조회하려면 query parameter를 반복해서 전달합니다. title: Status description: >- 위젯 상태 필터입니다. 허용값은 `draft`, `published`, `archived`이며 여러 상태를 조회하려면 query parameter를 반복해서 전달합니다. style: form explode: true - name: mode in: query required: false schema: anyOf: - enum: - chat - voice - callback type: string - type: 'null' description: 위젯 유형 필터입니다. 허용값은 `chat`, `voice`, `callback`입니다. title: Mode description: 위젯 유형 필터입니다. 허용값은 `chat`, `voice`, `callback`입니다. - name: sort_by in: query required: false schema: type: string description: 정렬 기준 필드입니다. `created_at`만 지원합니다. default: created_at title: Sort By enum: - created_at description: 정렬 기준 필드입니다. `created_at`만 지원합니다. - name: sort_order in: query required: false schema: type: string description: 정렬 방향입니다. 허용값은 `asc`, `desc`입니다. default: desc title: Sort Order enum: - asc - desc description: 정렬 방향입니다. 허용값은 `asc`, `desc`입니다. - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' title: Cursor description: 이전 응답의 `next_cursor` 값입니다. 다음 페이지를 조회할 때 그대로 전달합니다. description: 이전 응답의 `next_cursor` 값입니다. 다음 페이지를 조회할 때 그대로 전달합니다. - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 default: 50 title: Limit description: 반환할 최대 항목 수입니다. v3 목록 endpoint는 1~100을 허용합니다. description: 반환할 최대 항목 수입니다. v3 목록 endpoint는 1~100을 허용합니다. responses: '200': description: 성공 응답 content: application/json: schema: $ref: '#/components/schemas/PaginatedResponse_WidgetResponse_' '400': description: 요청 검증 오류 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validationError: summary: 요청 검증 오류 value: error: code: VALIDATION_ERROR message: Request validation failed. details: field: name reason: must not be blank '401': description: 인증이 필요합니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unauthorized: summary: Bearer 토큰 누락 또는 오류 value: error: code: UNAUTHORIZED message: Authentication is required. details: {} '403': description: 권한이 없습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: 권한이 없습니다. value: error: code: FORBIDDEN message: Permission denied. details: {} '404': description: 리소스를 찾을 수 없습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: notFound: summary: 리소스를 찾을 수 없습니다. value: error: code: RESOURCE_NOT_FOUND message: Resource not found. details: resource: agent '409': description: 충돌이 발생했습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: conflict: summary: 상태 충돌이 발생했습니다. value: error: code: CONFLICT message: The requested operation conflicts with current state. details: current_status: draft '429': description: >- 요청 한도를 초과했습니다. API 키 트래픽의 기본 한도는 조직당 초당 5건과 분당 120건입니다. Supabase JWT 트래픽의 기본 한도는 사용자당 초당 10건과 분당 240건이며, 조직 대시보드에는 분당 2,400건의 기본 보조 한도가 적용됩니다. 운영자가 한도를 변경할 수 있습니다. 초과한 버킷에 적용된 한도와 기간은 429 응답의 `X-RateLimit-Limit` 및 `X-RateLimit-Window` 헤더로 알립니다. 개별 경로의 자체 제한기가 생성한 429 응답에는 이 헤더가 없을 수 있습니다. headers: Retry-After: description: >- 초과한 공용 v3 인증 주체 제한기의 기간이 초기화될 때까지 남은 초입니다. 개별 경로의 자체 제한기가 생성한 429 응답에는 이 헤더가 없을 수 있습니다. schema: type: integer minimum: 1 X-RateLimit-Limit: description: >- 초과한 공용 v3 인증 주체 제한기 기간의 최대 요청 수입니다. 개별 경로의 자체 제한기가 생성한 429 응답에는 이 헤더가 없을 수 있습니다. schema: type: integer minimum: 1 X-RateLimit-Window: description: >- 초과한 공용 v3 인증 주체 제한기 기간의 길이입니다. 단위는 초입니다. 개별 경로의 자체 제한기가 생성한 429 응답에는 이 헤더가 없을 수 있습니다. schema: type: integer minimum: 1 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: rateLimited: summary: 요청 한도를 초과했습니다. value: error: code: RATE_LIMIT_EXCEEDED message: Too many requests. details: limit: 10 window_seconds: 1 scope: user '500': description: 서버 내부 오류가 발생했습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internalError: summary: 서버 내부 오류가 발생했습니다. value: error: code: INTERNAL_ERROR message: Internal server error. details: {} '503': description: 서비스를 일시적으로 사용할 수 없습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: serviceUnavailable: summary: 서비스를 일시적으로 사용할 수 없습니다. value: error: code: SERVICE_UNAVAILABLE message: Service temporarily unavailable. details: {} security: - BearerAuth: [] components: schemas: PaginatedResponse_WidgetResponse_: properties: items: items: $ref: '#/components/schemas/WidgetResponse' type: array title: Items description: 페이지 항목입니다. next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: 다음 페이지 커서입니다. 조회할 항목이 더 없으면 null입니다. total_count: type: integer title: Total Count description: 조건에 맞는 전체 항목 수입니다. type: object required: - items - total_count title: PaginatedResponse[WidgetResponse] ErrorResponse: type: object required: - error title: ErrorResponse description: 모든 실패 응답에서 사용하는 v3 error envelope입니다. examples: - error: code: VALIDATION_ERROR message: Request validation failed. details: field: name reason: must not be blank properties: error: $ref: '#/components/schemas/ErrorDetail' description: 오류 payload입니다. WidgetResponse: properties: id: type: string format: uuid title: Id description: 위젯 ID입니다. UUID이며 경로 파라미터 `widget_id`에 사용합니다. public_id: type: string title: Public Id description: 설치 코드의 `data-widget-id`입니다. `wgt_…` 형식이며 서버가 발급하고 읽기 전용입니다. organization_id: type: string format: uuid title: Organization Id description: 위젯을 소유한 조직 ID입니다. agent: $ref: '#/components/schemas/AgentMapping' description: '`agent_id`와 `agent_version`으로 구성된 에이전트 매핑 객체입니다.' status: type: string enum: - draft - published - archived title: Status description: >- 위젯 상태입니다. `draft`, `published`, `archived` 중 하나이며 생성·수정 요청에서는 바꿀 수 없습니다. mode: type: string enum: - chat - voice - callback title: Mode description: 위젯 유형입니다. `chat`, `voice`, `callback` 중 하나입니다. callback_from_number: anyOf: - type: string - type: 'null' title: Callback From Number description: 발신번호입니다. 없으면 null입니다. callback_presentation_number: anyOf: - type: string - type: 'null' title: Callback Presentation Number description: 수신자에게 표시할 번호입니다. null이면 `callback_from_number`가 표시됩니다. allowed_domains: items: type: string type: array title: Allowed Domains description: 설치를 허용한 도메인 목록입니다. rate_limit: anyOf: - $ref: '#/components/schemas/WidgetRateLimit' - type: 'null' description: 대화 시작 한도입니다. null이면 `standard`(방문자 IP당 분당 5회)를 적용합니다. branding: $ref: '#/components/schemas/WidgetBranding' description: 모양과 메시지 설정입니다. 설정하지 않은 키는 null입니다. published_at: anyOf: - type: integer - type: 'null' title: Published At description: >- 마지막 게시 시각입니다. unix milliseconds 형식입니다. 게시를 해제한 뒤에도 유지됩니다. 게시한 적이 없으면 null입니다. published_version_id: anyOf: - type: string format: uuid - type: 'null' title: Published Version Id description: 마지막 게시 버전 ID입니다. 게시를 해제한 뒤에도 유지됩니다. 게시한 적이 없으면 null입니다. created_at: type: integer title: Created At description: 리소스 생성 시각입니다. unix milliseconds 형식입니다. updated_at: type: integer title: Updated At description: 리소스 마지막 수정 시각입니다. unix milliseconds 형식입니다. type: object required: - id - public_id - organization_id - agent - status - mode - callback_from_number - callback_presentation_number - allowed_domains - rate_limit - branding - published_at - published_version_id - created_at - updated_at title: WidgetResponse ErrorDetail: type: object required: - code - message - details title: ErrorDetail description: 기계가 읽을 수 있는 v3 오류 상세 정보입니다. examples: - code: VALIDATION_ERROR message: Request validation failed. details: field: name reason: must not be blank properties: code: type: string title: Code description: 기계가 읽을 수 있는 오류 code입니다. message parsing 대신 이 값을 사용합니다. examples: - VALIDATION_ERROR message: type: string title: Message description: 사용자에게 표시할 수 있는 오류 메시지입니다. 프로그램 처리는 `code`를 사용합니다. examples: - Request validation failed. details: type: object title: Details additionalProperties: true description: 구조화된 context입니다. 주로 `field`, `reason`, `allowed_values`를 포함합니다. AgentMapping: additionalProperties: false description: >- `agent_id`와 `agent_version` 매핑입니다. 요청·응답 모두에서 에이전트 매핑이 필요한 경우 이 타입을 사용합니다. version 지정이 필요 없는 엔드포인트는 flat `agent_id: UUID`를 직접 받고 `AgentMapping`을 사용하지 않습니다. properties: agent_id: description: 에이전트 UUID입니다. format: uuid title: Agent Id type: string agent_version: default: current description: >- 에이전트 버전입니다. 허용값은 "current", "production", "v{n}"(n≥1)입니다. 보내지 않으면 "current"로 처리합니다. null 전송은 거부합니다. title: Agent Version type: string pattern: ^(current|production|v[1-9][0-9]*)$ examples: - current - production - v1 required: - agent_id title: AgentMapping type: object WidgetRateLimit: properties: preset: type: string enum: - standard - strict - custom title: Preset description: >- 시작 한도 프리셋입니다. `standard`는 분당 5회, `strict`는 분당 2회, `custom`은 `per_minute` 값을 사용합니다. per_minute: anyOf: - type: integer - type: 'null' title: Per Minute description: 분당 시작 한도입니다. `custom`에서 필수이며 범위는 1~30입니다. 다른 프리셋에서는 무시됩니다. type: object required: - preset title: WidgetRateLimit WidgetBranding: properties: title: anyOf: - type: string - type: 'null' title: Title description: 방문자에게 보이는 위젯 제목입니다. accent_color: anyOf: - type: string - type: 'null' title: Accent Color description: 강조 색상입니다. 형식은 `#RRGGBB`입니다. null이면 기본 강조 색상을 사용합니다. orb_colors: anyOf: - $ref: '#/components/schemas/WidgetOrbColors' - type: 'null' description: 아바타 색상입니다. null이면 기본 팔레트를 유지합니다. styles: anyOf: - $ref: '#/components/schemas/WidgetStyles' - type: 'null' description: 모서리 반경 설정입니다. theme: anyOf: - type: string enum: - light - dark - type: 'null' title: Theme description: 테마입니다. `light` 또는 `dark`이며 기본값은 `light`입니다. logo_url: anyOf: - type: string - type: 'null' title: Logo Url description: 로고 이미지 URL입니다. popup_message: anyOf: - type: string - type: 'null' title: Popup Message description: 인사 메시지입니다. popup_delay_seconds: anyOf: - type: number - type: 'null' title: Popup Delay Seconds description: 인사 메시지를 띄우기 전 대기 시간입니다. 단위는 초입니다. auto_open: anyOf: - type: boolean - type: 'null' title: Auto Open description: true이면 페이지 로드 시 위젯 창을 자동으로 엽니다. suggested_replies: anyOf: - items: type: string type: array - type: 'null' title: Suggested Replies description: 채팅 추천 답변 목록입니다. disclaimer_text: anyOf: - type: string - type: 'null' title: Disclaimer Text description: 채팅 면책 문구입니다. markdown: anyOf: - type: boolean - type: 'null' title: Markdown description: true이면 에이전트 답변을 마크다운 형식으로 렌더링합니다. link_allowed_hosts: anyOf: - items: type: string type: array - type: 'null' title: Link Allowed Hosts description: 마크다운 링크를 허용할 호스트 목록입니다. 단독 `*`는 모든 호스트를 허용합니다. transcript: anyOf: - type: boolean - type: 'null' title: Transcript description: true이면 음성 통화 중 대화 내용을 텍스트로 표시합니다. fab_text: anyOf: - type: string - type: 'null' title: Fab Text description: 위젯 버튼 텍스트입니다. placement: anyOf: - type: string enum: - bottom-right - bottom-left - bottom-center - type: 'null' title: Placement description: >- 위젯 버튼 위치입니다. `bottom-right`(기본값), `bottom-left`, `bottom-center` 중 하나입니다. panel_size: anyOf: - type: string enum: - compact - full - type: 'null' title: Panel Size description: 위젯 창 크기입니다. `compact`(기본값) 또는 `full`입니다. white_label: anyOf: - type: boolean - type: 'null' title: White Label description: true이면 Powered by vox.ai를 숨깁니다. dynamic_variables: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Dynamic Variables description: >- 게시 시 고정하는 동적 변수입니다. 설치 코드의 `data-dynamic`으로 값을 덮어쓸 수 있는 키는 여기에 게시한 키뿐입니다. terms_url: anyOf: - type: string - type: 'null' title: Terms Url description: 콜백 폼에 표시할 약관 URL입니다. callback_fields: anyOf: - items: $ref: '#/components/schemas/WidgetCallbackField' type: array - type: 'null' title: Callback Fields description: 콜백 폼 입력 항목입니다. type: object title: WidgetBranding WidgetOrbColors: properties: primary: anyOf: - type: string - type: 'null' title: Primary description: 아바타 색상 1입니다. 형식은 `#RRGGBB`입니다. null이면 기본 팔레트를 사용합니다. secondary: anyOf: - type: string - type: 'null' title: Secondary description: 아바타 색상 2입니다. 형식은 `#RRGGBB`입니다. null이면 기본 팔레트를 사용합니다. type: object title: WidgetOrbColors WidgetStyles: properties: button_radius: anyOf: - type: number - type: 'null' title: Button Radius description: 위젯 버튼 모서리입니다. 단위는 픽셀입니다. input_radius: anyOf: - type: number - type: 'null' title: Input Radius description: 입력창 모서리 반경입니다. 단위는 픽셀입니다. bubble_radius: anyOf: - type: number - type: 'null' title: Bubble Radius description: 채팅 말풍선 모서리 반경입니다. 단위는 픽셀입니다. type: object title: WidgetStyles WidgetCallbackField: properties: key: type: string title: Key description: 동적 변수 키입니다. `^[a-z][a-z0-9_]*$`와 일치해야 하며 중복될 수 없습니다. label: type: string title: Label description: 방문자에게 보이는 필드 라벨입니다. type: type: string enum: - text - textarea - select title: Type description: >- 입력 유형입니다. `text`, `textarea`, `select` 중 하나이며 `select`는 비어 있지 않은 `options`가 필요합니다. placeholder: anyOf: - type: string - type: 'null' title: Placeholder description: 입력란 안내 문구입니다. 선택 사항입니다. required: anyOf: - type: boolean - type: 'null' title: Required description: 방문자가 필드를 채워야 하는지 여부입니다. options: anyOf: - items: type: string type: array - type: 'null' title: Options description: '`select` 유형의 선택지 목록입니다. `type`이 `select`이면 필수이며 비어 있으면 안 됩니다.' type: object required: - key - label - type title: WidgetCallbackField securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: Organization API key description: '조직 API 키를 `Authorization: Bearer ` 형식으로 보냅니다.' ````