개발자 문서

PUSH API · v1a

API 레퍼런스

공개 OpenAPI와 endpoints.yaml에서 경로·인증을 교차 확인하고 생성합니다. 실행 버튼은 없습니다. JSON Schema의 required, enum, oneOf와 범위를 함께 확인하세요.

OpenAPI 3.1 JSON 내려받기 · v1a

요청작업
POST /v1/project-messages통합 서버 키에 지정한 같은 프로젝트 환경의 앱들에 원자적으로 발송 접수
GET /v1/project-messages/{id}같은 통합 키가 접수한 결과를 24시간 동안 조회. 실시간 기기 전달 상태가 아니다.
GET /v1/installations/{installation_id}/notification-channelsRead the Android notification channels for the authenticated installation's app environment
POST /v1/identity-tokens구형 kitid1 호환용 native 로그인 증명을 발급한다
GET /v1/installations/{id}/identity자기 설치본의 현재 binding과 마지막 native 작업을 확인한다
POST /v1/installations/{id}/identity자기 설치본의 로그인 또는 로그아웃을 조건부 수행한다 (새 작업 분당 20회)
GET /v1/installations/{id}/identity-policy자기 설치본의 현재 binding과 서버가 정한 로그인 인증 정책을 함께 확인한다
POST /v1/notification-receiptsiOS 확장에 발급한 단일 배송 capability로 수신 관측을 기록한다
POST /v1/installations/{id}:sync-activity-distribution선택적 최근 28일 UTC 시간대별 foreground 활동 스냅샷을 동기화한다
POST /v1/installations/{id}:record-notification-event명시적 opt-in 배송의 SDK 수신 또는 클릭 관측을 기록한다
POST /v1/installations/{id}:sync-audienceSDK 메타데이터와 누적 foreground 세션 관측을 동기화한다. 동일 sequence 재전송은 누적되지 않는다
POST /v1/installations/{id}:set-client-tags현재 installation binding의 SDK 문자열 태그 전체 스냅샷을 교체한다
POST /v1/installations설치본 등록·갱신. 없으면 익명 사용자를 자동으로 만들고 token rotation은 cooldown으로 제한한다
POST /v1/installations/{id}:identify로그인 — external_id 가 가리키는 사용자로 재바인딩한다
POST /v1/installations/{id}:logout로그아웃 — 새 익명 사용자로 되돌린다
POST /v1/installations/{id}:transfer이미 있는 다른 사용자에게 기기를 이전한다
GET /v1/app-users/{id}사용자 현재 상태와 묶인 구독의 bounded keyset page
GET /v1/app-users/by-external-id/{external_id}고객사 식별자로 사용자와 묶인 구독의 bounded keyset page를 찾는다
POST /v1/push-subscriptions기기 푸시 주소를 등록한다. 토큰은 봉인해서 저장한다
POST /v1/push-subscriptions:unregister현재 주소와 정확히 일치할 때만 기기 푸시 주소를 등록 해제한다
POST /v1/push-subscriptions/{id}/addresses주소 세대를 회전한다
POST /v1/push-subscriptions/{id}:invalidate지금 살아 있는 주소 세대를 무효화한다
POST /v1/push-subscriptions/{id}/addresses/{generation}:invalidate정확히 그 세대만 무효화한다
POST /v1/installations/{id}/permission-observationsOS 알림 권한 관측을 기록한다. 고치지 않고 쌓는다
POST /v1/installations/{id}:set-push-preference앱 안 알림 설정을 바꾼다
POST /v1/app-users/{id}/marketing-consents마케팅 동의를 기록한다. 철회도 새로 쌓는다
GET /v1/app-users/{id}/marketing-consents마케팅 동의 이력의 bounded keyset page
GET /v1/app-users/{id}/delivery-eligibility지금 이 사람에게 보낼 수 있나, 안 되면 왜
POST /v1/messages발송 접수. 한 사람 또는 여러 사람(최대 20000). 실제 전송은 워커가 한다
POST /v1/broadcasts이 앱의 모두에게 발송. 대상 행은 뒤에서 만들어진다
GET /v1/messages/{id}요청 단위 결과 요약
GET /v1/messages/{id}/deliveries대상별 결과
GET /v1/deliveries사람이 닫아야 하는 미결 발송 목록
POST /v1/messages/{id}:stop이 메시지의 남은 발송을 멈춘다. 앱 전체를 끄지 않고
POST /v1/messages/{id}/deliveries/{subscription_id}:resolve-unknown결과불명 발송을 운영자가 수동으로 종결한다
GET /v1/app-environments/{id}/dispatch-control지금 멈춰 있는가와 현재 제어 세대
GET /v1/app-environments/{id}/address-breaker주소 대량 삭제 차단기가 걸려 있는가와 걸린 근거
POST /v1/app-environments/{id}:reset-address-breaker차단기를 푼다. 대량 주소 삭제를 다시 켜는 일이라 사유가 필요하다
POST /v1/app-environments/{id}:pause-dispatch긴급 정지. 세대를 올려 대기 중인 것도 막는다
POST /v1/app-environments/{id}:resume-dispatch발송 재개
POST /v1/push-provider-connections공급자 자격증명을 등록한다. 원문은 봉인되어 저장된다
GET /v1/push-provider-connections연결 health와 최신 후보·실제 active 버전·dispatch readiness를 조회한다
POST /v1/push-provider-connections/{id}:rotate-credentialPENDING 후보 버전을 더한다. 검증 PASS 전까지 기존 active로 계속 발송한다
POST /v1/push-provider-connections/{id}:recover-credential기존 active 키의 신원을 복원할 수 없는 터미널 상태에서만 명시적 복구 후보를 생성한다
POST /v1/push-provider-connections/{id}:verify다시 확인해 달라고 요청한다. 확인은 워커가 한다
PUT /v1/attribute-definitions/{key}속성 키와 타입을 등록한다
GET /v1/attribute-definitions등록된 속성 정의의 bounded keyset 목록
POST /v1/app-users/{id}:set-attributes속성 값을 기록한다. 더 새로운 관측만 이긴다
PUT /v1/event-definitions/{name}이벤트 이름을 등록한다
GET /v1/event-definitions등록된 이벤트 정의의 bounded keyset 목록
POST /v1/app-events이벤트를 배치로 기록한다. 클라이언트 id 로 중복을 거른다
GET /v1/registry/enums상태값 레지스트리 전체
GET /v1/registry/error-codes오류 코드 레지스트리 전체
GET /v1/registry/message-fields메시지 필드 레지스트리 전체

POST /v1/project-messages

통합 서버 키에 지정한 같은 프로젝트 환경의 앱들에 원자적으로 발송 접수

인증: projectApiKey: messages:send

계약 원문 설명

통합 서버 키에 지정한 같은 프로젝트 환경의 앱들에 원자적으로 발송 접수

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
Kits-Idempotency-Key · header필수
{
  "type": "string",
  "minLength": 1,
  "maxLength": 255,
  "pattern": "^[\\x20-\\x7E]+$"
}

요청 본문

본문 필수

application/json

{
  "allOf": [
    {
      "$ref": "#/components/schemas/MessageRequest"
    },
    {
      "type": "object",
      "properties": {
        "target": {
          "oneOf": [
            {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "external_id"
              ],
              "properties": {
                "external_id": {
                  "type": "string",
                  "minLength": 1
                }
              }
            },
            {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "external_ids"
              ],
              "properties": {
                "external_ids": {
                  "type": "array",
                  "minItems": 1,
                  "maxItems": 20000,
                  "items": {
                    "type": "string",
                    "minLength": 1
                  }
                }
              }
            }
          ]
        }
      }
    }
  ]
}

공통 스키마: MessageRequest

응답

HTTP 202

원자적 접수 결과. 실제 기기 수신 보장이 아니며 동일 키의 재시도는 24시간 동안 같은 결과를 반환한다. 대상에게 활성 구독이 없는 앱은 applications에서 빠지고 메시지를 만들지 않는다(모든 앱이 비면 키의 앱 하나만 0건으로 남고, 같은 키에서는 늘 같은 앱이다).

application/json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "origin",
    "accepted_at",
    "idempotency",
    "targeted_subscriptions",
    "ignored_fields",
    "status_url",
    "applications"
  ],
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^pmsg_[0-9a-f]{32}$"
    },
    "origin": {
      "type": "string",
      "const": "TRANSACTIONAL_API"
    },
    "accepted_at": {
      "type": "string",
      "format": "date-time"
    },
    "idempotency": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "replayed"
      ],
      "properties": {
        "replayed": {
          "type": "boolean"
        }
      }
    },
    "targeted_subscriptions": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991,
      "description": "The sum of the listed applications' targeted_subscriptions. Unreachable (INVALIDATED) push subscriptions are not targeted."
    },
    "ignored_fields": {
      "type": "array",
      "description": "The sorted union of the listed applications' ignored_fields. An app that is left out (no active subscription) contributes none.",
      "maxItems": 64,
      "uniqueItems": true,
      "items": {
        "type": "string"
      }
    },
    "status_url": {
      "type": "string",
      "pattern": "^/v1/project-messages/pmsg_[0-9a-f]{32}$"
    },
    "applications": {
      "type": "array",
      "description": "One entry per allowlisted app whose target had at least one active subscription when the message was accepted. An app with none is left out and creates no message. When every app has none, exactly one of the key's apps is listed with targeted_subscriptions 0 (always the same app for a given key), so the receipt always has an id and accepted_at.",
      "minItems": 1,
      "maxItems": 8,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "app_environment_id",
          "platform",
          "message_id",
          "targeted_subscriptions",
          "ignored_fields"
        ],
        "properties": {
          "app_environment_id": {
            "type": "string",
            "pattern": "^aenv_[A-Za-z0-9_-]{1,123}$"
          },
          "platform": {
            "type": "string",
            "enum": [
              "ANDROID",
              "IOS"
            ]
          },
          "message_id": {
            "type": "string",
            "pattern": "^msg_[A-Za-z0-9_-]{1,123}$"
          },
          "targeted_subscriptions": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Active push subscriptions of the target in this app when the message was accepted. A subscription whose push address the provider permanently rejected, an operator or the API revoked, or that moved to another installation is INVALIDATED and is not counted or sent to; it becomes active again when that installation registers a new token."
          },
          "ignored_fields": {
            "type": "array",
            "maxItems": 64,
            "uniqueItems": true,
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

GET /v1/project-messages/{id}

같은 통합 키가 접수한 결과를 24시간 동안 조회. 실시간 기기 전달 상태가 아니다.

인증: projectApiKey: messages:read

계약 원문 설명

같은 통합 키가 접수한 결과를 24시간 동안 조회. 실시간 기기 전달 상태가 아니다.

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
id · path필수
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

요청 본문

응답

HTTP 200

앱별 message_id를 포함한 최초 접수 영수증. 각 메시지는 해당 앱의 대시보드 발송 이력에서 조회한다.

application/json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "origin",
    "accepted_at",
    "idempotency",
    "targeted_subscriptions",
    "ignored_fields",
    "status_url",
    "applications"
  ],
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^pmsg_[0-9a-f]{32}$"
    },
    "origin": {
      "type": "string",
      "const": "TRANSACTIONAL_API"
    },
    "accepted_at": {
      "type": "string",
      "format": "date-time"
    },
    "idempotency": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "replayed"
      ],
      "properties": {
        "replayed": {
          "type": "boolean"
        }
      }
    },
    "targeted_subscriptions": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991,
      "description": "The sum of the listed applications' targeted_subscriptions. Unreachable (INVALIDATED) push subscriptions are not targeted."
    },
    "ignored_fields": {
      "type": "array",
      "description": "The sorted union of the listed applications' ignored_fields. An app that is left out (no active subscription) contributes none.",
      "maxItems": 64,
      "uniqueItems": true,
      "items": {
        "type": "string"
      }
    },
    "status_url": {
      "type": "string",
      "pattern": "^/v1/project-messages/pmsg_[0-9a-f]{32}$"
    },
    "applications": {
      "type": "array",
      "description": "One entry per allowlisted app whose target had at least one active subscription when the message was accepted. An app with none is left out and creates no message. When every app has none, exactly one of the key's apps is listed with targeted_subscriptions 0 (always the same app for a given key), so the receipt always has an id and accepted_at.",
      "minItems": 1,
      "maxItems": 8,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "app_environment_id",
          "platform",
          "message_id",
          "targeted_subscriptions",
          "ignored_fields"
        ],
        "properties": {
          "app_environment_id": {
            "type": "string",
            "pattern": "^aenv_[A-Za-z0-9_-]{1,123}$"
          },
          "platform": {
            "type": "string",
            "enum": [
              "ANDROID",
              "IOS"
            ]
          },
          "message_id": {
            "type": "string",
            "pattern": "^msg_[A-Za-z0-9_-]{1,123}$"
          },
          "targeted_subscriptions": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Active push subscriptions of the target in this app when the message was accepted. A subscription whose push address the provider permanently rejected, an operator or the API revoked, or that moved to another installation is INVALIDATED and is not counted or sent to; it becomes active again when that installation registers a new token."
          },
          "ignored_fields": {
            "type": "array",
            "maxItems": 64,
            "uniqueItems": true,
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

GET /v1/installations/{installation_id}/notification-channels

Read the Android notification channels for the authenticated installation's app environment

인증: deviceToken: 자기 앱 설치에 한정

계약 원문 설명

Read the Android notification channels for the authenticated installation's app environment

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
installation_id · path필수
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

요청 본문

응답

HTTP 200

Current installation device token only; the path must match that installation. Returns the complete current configuration including archived channels. Revision zero with empty arrays means unconfigured. Android user channel settings take precedence; archiving does not delete OS channels.

application/json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "app_environment_id",
    "revision",
    "groups",
    "channels"
  ],
  "properties": {
    "app_environment_id": {
      "type": "string",
      "minLength": 6,
      "maxLength": 128,
      "pattern": "^aenv_[A-Za-z0-9_-]{1,123}$(?![\\s\\S])"
    },
    "revision": {
      "type": "integer",
      "minimum": 0,
      "maximum": 2147483647
    },
    "groups": {
      "type": "array",
      "maxItems": 20,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string",
            "maxLength": 40,
            "pattern": "^kitcgrp_[0-9a-f]{32}$",
            "description": "Immutable group identifier."
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "pattern": "^(?=[\\s\\S]*\\S)[^\\u0000-\\u001f\\u007f-\\u009f]+$(?![\\s\\S])"
          }
        }
      }
    },
    "channels": {
      "type": "array",
      "maxItems": 100,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "name",
          "description",
          "group_id",
          "importance",
          "sound",
          "vibration_enabled",
          "lights_enabled",
          "light_color",
          "show_badge",
          "lockscreen_visibility",
          "archived"
        ],
        "properties": {
          "id": {
            "type": "string",
            "maxLength": 39,
            "pattern": "^kitchn_[0-9a-f]{32}$",
            "description": "Immutable channel identifier."
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "pattern": "^(?=[\\s\\S]*\\S)[^\\u0000-\\u001f\\u007f-\\u009f]+$(?![\\s\\S])"
          },
          "description": {
            "type": "string",
            "maxLength": 500,
            "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f]*$(?![\\s\\S])"
          },
          "group_id": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 40,
            "pattern": "^kitcgrp_[0-9a-f]{32}$"
          },
          "importance": {
            "type": "string",
            "enum": [
              "MIN",
              "LOW",
              "DEFAULT",
              "HIGH"
            ]
          },
          "sound": {
            "type": "string",
            "maxLength": 80,
            "pattern": "^(?:default|none|[a-z][a-z0-9_]{0,79})$(?![\\s\\S])",
            "description": "default for the system sound, none for silence, or a raw Android resource name."
          },
          "vibration_enabled": {
            "type": "boolean"
          },
          "lights_enabled": {
            "type": "boolean"
          },
          "light_color": {
            "type": "string",
            "maxLength": 7,
            "pattern": "^#[0-9A-Fa-f]{6}$"
          },
          "show_badge": {
            "type": "boolean"
          },
          "lockscreen_visibility": {
            "type": "string",
            "enum": [
              "PUBLIC",
              "PRIVATE",
              "SECRET"
            ]
          },
          "archived": {
            "type": "boolean"
          }
        }
      }
    }
  }
}
HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

POST /v1/identity-tokens

구형 kitid1 호환용 native 로그인 증명을 발급한다

인증: apiKey: identity:write

계약 원문 설명

구형 kitid1 호환용 native 로그인 증명을 발급한다

경로·쿼리·헤더 입력

이 작업에 별도 선언된 parameter가 없습니다.

요청 본문

본문 필수

application/json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "installation_id",
    "expected_binding_id",
    "operation_id",
    "external_id"
  ],
  "properties": {
    "installation_id": {
      "type": "string",
      "pattern": "^inst_[0-9a-f]{32}$",
      "maxLength": 37
    },
    "expected_binding_id": {
      "type": "string",
      "format": "uuid",
      "maxLength": 36,
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "operation_id": {
      "type": "string",
      "format": "uuid",
      "maxLength": 36,
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "external_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    }
  }
}

응답

HTTP 200

성공

application/json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "token",
    "expires_at"
  ],
  "properties": {
    "token": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4096,
      "description": "Opaque sensitive proof; never log or parse in client applications."
    },
    "expires_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}
HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

GET /v1/installations/{id}/identity

자기 설치본의 현재 binding과 마지막 native 작업을 확인한다

인증: deviceToken: 자기 앱 설치에 한정

계약 원문 설명

자기 설치본의 현재 binding과 마지막 native 작업을 확인한다

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
id · path필수
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

요청 본문

응답

HTTP 200

Cache-Control no-store. 마지막 native 작업의 결과 binding이 아직 현재 binding일 때만 operation_id가 있다. 이후 server rebind 등이 있었다면 null이다.

application/json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "binding_id",
    "app_user",
    "operation_id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    },
    "binding_id": {
      "type": "string",
      "format": "uuid"
    },
    "operation_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "app_user": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "external_id",
        "anonymous"
      ],
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1
        },
        "external_id": {
          "type": [
            "string",
            "null"
          ]
        },
        "anonymous": {
          "type": "boolean"
        }
      }
    }
  }
}
HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

POST /v1/installations/{id}/identity

자기 설치본의 로그인 또는 로그아웃을 조건부 수행한다 (새 작업 분당 20회)

인증: deviceToken: 자기 앱 설치에 한정

계약 원문 설명

자기 설치본의 로그인 또는 로그아웃을 조건부 수행한다 (새 작업 분당 20회)

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
id · path필수
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

요청 본문

본문 필수

application/json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "operation_id",
    "expected_binding_id",
    "action"
  ],
  "properties": {
    "operation_id": {
      "type": "string",
      "format": "uuid",
      "maxLength": 36,
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "expected_binding_id": {
      "type": "string",
      "format": "uuid",
      "maxLength": 36,
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "action": {
      "type": "string",
      "enum": [
        "LOGIN",
        "LOGOUT"
      ]
    },
    "token": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4096
    },
    "external_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    },
    "expected_policy_revision": {
      "type": "integer",
      "minimum": 0,
      "maximum": 2147483647,
      "description": "AUTO SDK의 LOGIN에서 조회한 정책 revision. 변경 시 IDENTITY_REBIND_CONFLICT이며 새 정책과 현재 binding을 다시 확인한다. 구형 명시 모드 SDK 호환을 위해 선택 사항이고 LOGOUT에는 금지한다."
    }
  },
  "allOf": [
    {
      "if": {
        "properties": {
          "action": {
            "const": "LOGIN"
          }
        }
      },
      "then": {
        "oneOf": [
          {
            "required": [
              "token"
            ],
            "not": {
              "required": [
                "external_id"
              ]
            }
          },
          {
            "required": [
              "external_id"
            ],
            "not": {
              "required": [
                "token"
              ]
            }
          }
        ]
      }
    },
    {
      "if": {
        "properties": {
          "action": {
            "const": "LOGOUT"
          }
        }
      },
      "then": {
        "not": {
          "anyOf": [
            {
              "required": [
                "token"
              ]
            },
            {
              "required": [
                "external_id"
              ]
            },
            {
              "required": [
                "expected_policy_revision"
              ]
            }
          ]
        }
      }
    }
  ]
}

응답

HTTP 200

Cache-Control no-store. 마지막 native 작업의 결과 binding이 아직 현재 binding일 때만 operation_id가 있다. 이후 server rebind 등이 있었다면 null이다.

application/json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "binding_id",
    "app_user",
    "operation_id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    },
    "binding_id": {
      "type": "string",
      "format": "uuid"
    },
    "operation_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "app_user": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "external_id",
        "anonymous"
      ],
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1
        },
        "external_id": {
          "type": [
            "string",
            "null"
          ]
        },
        "anonymous": {
          "type": "boolean"
        }
      }
    }
  }
}
HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

GET /v1/installations/{id}/identity-policy

자기 설치본의 현재 binding과 서버가 정한 로그인 인증 정책을 함께 확인한다

인증: deviceToken: 자기 앱 설치에 한정

계약 원문 설명

자기 설치본의 현재 binding과 서버가 정한 로그인 인증 정책을 함께 확인한다

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
id · path필수
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

요청 본문

응답

HTTP 200

Cache-Control no-store. 기기 인증으로 자기 설치본만 조회하며 binding과 정책을 같은 트랜잭션에서 읽는다. 정책은 프로젝트 환경마다 하나라서 같은 프로젝트 환경의 앱은 같은 mode와 revision을 받고, app_environment_id는 기기 자신의 앱 환경이다. 정책 미설정 시 VERIFIED와 revision 0이다. SDK는 알 수 없는 응답이나 조회 실패를 BASIC으로 해석하지 않는다. 기존 identity 응답은 변경하지 않는다.

application/json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "binding_id",
    "app_user",
    "operation_id",
    "identity_policy"
  ],
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    },
    "binding_id": {
      "type": "string",
      "format": "uuid"
    },
    "operation_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "app_user": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "external_id",
        "anonymous"
      ],
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1
        },
        "external_id": {
          "type": [
            "string",
            "null"
          ]
        },
        "anonymous": {
          "type": "boolean"
        }
      }
    },
    "identity_policy": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "app_environment_id",
        "mode",
        "revision"
      ],
      "properties": {
        "app_environment_id": {
          "type": "string",
          "pattern": "^aenv_[0-9a-f]{32}$"
        },
        "mode": {
          "type": "string",
          "enum": [
            "BASIC",
            "VERIFIED"
          ]
        },
        "revision": {
          "type": "integer",
          "minimum": 0,
          "maximum": 2147483647
        }
      }
    }
  }
}
HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

POST /v1/notification-receipts

iOS 확장에 발급한 단일 배송 capability로 수신 관측을 기록한다

인증: notificationReceipt: 발급된 단일 배송의 수신 보고만

계약 원문 설명

iOS 확장에 발급한 단일 배송 capability로 수신 관측을 기록한다

경로·쿼리·헤더 입력

이 작업에 별도 선언된 parameter가 없습니다.

요청 본문

본문 필수

application/json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "delivery_id",
    "event"
  ],
  "properties": {
    "delivery_id": {
      "type": "string",
      "format": "uuid",
      "maxLength": 36
    },
    "event": {
      "type": "string",
      "const": "RECEIVED"
    }
  }
}

응답

HTTP 200

성공

application/json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "delivery_id",
    "event",
    "recorded"
  ],
  "properties": {
    "delivery_id": {
      "type": "string",
      "format": "uuid"
    },
    "event": {
      "type": "string",
      "const": "RECEIVED"
    },
    "recorded": {
      "type": "boolean"
    }
  }
}
HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

POST /v1/installations/{id}:sync-activity-distribution

선택적 최근 28일 UTC 시간대별 foreground 활동 스냅샷을 동기화한다

인증: deviceToken: 자기 앱 설치에 한정

계약 원문 설명

선택적 최근 28일 UTC 시간대별 foreground 활동 스냅샷을 동기화한다

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
id · path필수
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

요청 본문

본문 필수

application/json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "schema_version",
    "binding_id",
    "sequence",
    "timezone",
    "days"
  ],
  "x-kits-max-utf8-bytes": 16384,
  "properties": {
    "schema_version": {
      "type": "integer",
      "const": 1,
      "minimum": 1,
      "maximum": 1
    },
    "binding_id": {
      "type": "string",
      "format": "uuid",
      "maxLength": 36
    },
    "sequence": {
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "timezone": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "IANA time zone; UTC is accepted."
    },
    "days": {
      "type": "array",
      "maxItems": 28,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "date",
          "hours"
        ],
        "properties": {
          "date": {
            "type": "string",
            "format": "date",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
          },
          "hours": {
            "type": "array",
            "minItems": 24,
            "maxItems": 24,
            "items": {
              "type": "integer",
              "minimum": 0,
              "maximum": 3600
            }
          }
        }
      }
    }
  }
}

응답

HTTP 200

성공

application/json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "schema_version",
    "binding_id",
    "sequence",
    "applied"
  ],
  "properties": {
    "schema_version": {
      "type": "integer",
      "const": 1,
      "minimum": 1,
      "maximum": 1
    },
    "binding_id": {
      "type": "string",
      "format": "uuid"
    },
    "sequence": {
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "applied": {
      "type": "boolean"
    }
  }
}
HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

POST /v1/installations/{id}:record-notification-event

명시적 opt-in 배송의 SDK 수신 또는 클릭 관측을 기록한다

인증: deviceToken: 자기 앱 설치에 한정

계약 원문 설명

명시적 opt-in 배송의 SDK 수신 또는 클릭 관측을 기록한다

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
id · path필수
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

요청 본문

본문 필수

application/json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "delivery_id",
    "event"
  ],
  "properties": {
    "delivery_id": {
      "type": "string",
      "format": "uuid",
      "maxLength": 36
    },
    "event": {
      "type": "string",
      "enum": [
        "RECEIVED",
        "CLICKED"
      ]
    },
    "occurred_at": {
      "type": "string",
      "format": "date-time",
      "maxLength": 24,
      "description": "UTC Z timestamp. Untrusted; at most 35 days old or five minutes in the future."
    }
  }
}

응답

HTTP 200

중복은 recorded=false이며 원래 시각과 관측을 변경하지 않는다

application/json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "delivery_id",
    "event",
    "recorded"
  ],
  "properties": {
    "delivery_id": {
      "type": "string",
      "format": "uuid"
    },
    "event": {
      "type": "string",
      "enum": [
        "RECEIVED",
        "CLICKED"
      ]
    },
    "recorded": {
      "type": "boolean"
    }
  }
}
HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

POST /v1/installations/{id}:sync-audience

SDK 메타데이터와 누적 foreground 세션 관측을 동기화한다. 동일 sequence 재전송은 누적되지 않는다

인증: deviceToken: 자기 앱 설치에 한정

계약 원문 설명

SDK 메타데이터와 누적 foreground 세션 관측을 동기화한다. 동일 sequence 재전송은 누적되지 않는다

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
id · path필수
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

요청 본문

본문 필수

application/json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "sequence",
    "metadata"
  ],
  "properties": {
    "sequence": {
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "metadata": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "app_version": {
          "type": "string",
          "maxLength": 128,
          "x-kits-max-utf8-bytes": 512
        },
        "language": {
          "type": "string",
          "pattern": "^[a-z]{2,3}$"
        },
        "locale": {
          "type": "string",
          "maxLength": 35,
          "pattern": "^[a-z]{2,3}(?:-[A-Z][a-z]{3})?(?:-[A-Z]{2}|-[0-9]{3})?$"
        },
        "timezone": {
          "type": "string",
          "maxLength": 64,
          "pattern": "^[A-Za-z0-9_+/-]+$",
          "description": "IANA time zone such as Asia/Seoul"
        }
      }
    },
    "activity": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "first_session_at",
        "last_session_at",
        "session_count",
        "total_duration_ms"
      ],
      "properties": {
        "first_session_at": {
          "type": "string",
          "format": "date-time",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,3})?Z$"
        },
        "last_session_at": {
          "type": "string",
          "format": "date-time",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,3})?Z$"
        },
        "session_count": {
          "type": "integer",
          "minimum": 1,
          "maximum": 9007199254740991
        },
        "total_duration_ms": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        }
      }
    }
  }
}

응답

HTTP 200

성공

application/json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "sequence",
    "applied"
  ],
  "properties": {
    "sequence": {
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "applied": {
      "type": "boolean"
    }
  }
}
HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

POST /v1/installations/{id}:set-client-tags

현재 installation binding의 SDK 문자열 태그 전체 스냅샷을 교체한다

인증: deviceToken: 자기 앱 설치에 한정

계약 원문 설명

현재 installation binding의 SDK 문자열 태그 전체 스냅샷을 교체한다

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
id · path필수
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

요청 본문

본문 필수

application/json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "sequence",
    "binding_id",
    "tags"
  ],
  "properties": {
    "sequence": {
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "binding_id": {
      "type": "string",
      "format": "uuid"
    },
    "tags": {
      "type": "object",
      "maxProperties": 64,
      "propertyNames": {
        "type": "string",
        "pattern": "^(?!(kits_|consent_|billing_|entitlement_))[a-z][a-z0-9_]{0,62}$"
      },
      "additionalProperties": {
        "type": "string",
        "maxLength": 256,
        "x-kits-max-utf8-bytes": 1024
      }
    }
  }
}

응답

HTTP 200

성공

application/json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "sequence",
    "applied",
    "binding_id"
  ],
  "properties": {
    "sequence": {
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "applied": {
      "type": "boolean"
    },
    "binding_id": {
      "type": "string",
      "format": "uuid"
    }
  }
}
HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

POST /v1/installations

설치본 등록·갱신. 없으면 익명 사용자를 자동으로 만들고 token rotation은 cooldown으로 제한한다

인증: apiKey: identity:write OR apiKey: installations:enroll

계약 원문 설명

설치본 등록·갱신. 없으면 익명 사용자를 자동으로 만들고 token rotation은 cooldown으로 제한한다

경로·쿼리·헤더 입력

이 작업에 별도 선언된 parameter가 없습니다.

요청 본문

본문 필수

application/json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "client_installation_key"
  ],
  "properties": {
    "client_installation_key": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "platform": {
      "type": "string",
      "enum": [
        "IOS",
        "ANDROID"
      ]
    },
    "app_version": {
      "type": "string",
      "maxLength": 64
    },
    "native_contract_version": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1,
      "enum": [
        1
      ]
    },
    "native_capabilities": {
      "type": "array",
      "minItems": 1,
      "maxItems": 11,
      "uniqueItems": true,
      "description": "ASCII 오름차순이어야 하며 플랫폼과 충돌하는 주소 capability를 함께 보낼 수 없다",
      "items": {
        "type": "string",
        "enum": [
          "ANDROID_APP_DISPLAY_V1",
          "APNS_DEVICE_TOKEN",
          "DURABLE_SYNC",
          "FCM_FID",
          "FCM_REGISTRATION_TOKEN_LEGACY",
          "FOREGROUND_FORWARD",
          "IDENTITY_HANDOFF",
          "NOTIFICATION_CLICK",
          "PAYLOAD_V1",
          "PERMISSION_OBSERVATION",
          "PUSH_PREFERENCE"
        ]
      }
    }
  },
  "oneOf": [
    {
      "not": {
        "anyOf": [
          {
            "required": [
              "native_contract_version"
            ]
          },
          {
            "required": [
              "native_capabilities"
            ]
          }
        ]
      }
    },
    {
      "required": [
        "native_contract_version",
        "native_capabilities"
      ]
    }
  ]
}

응답

HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 2XX

새 설치본은 201, cooldown 뒤 기존 설치본 갱신은 200이며 서버가 저장한 native 계약을 echo한다. 같은 installation이 최근 token을 회전했으면 project-environment 설정의 남은 초를 Retry-After에 담은 429 RATE_LIMITED를 반환한다

application/json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "app_user",
    "binding_id",
    "device_token",
    "native_contract"
  ],
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    },
    "app_user": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "external_id",
        "anonymous"
      ],
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1
        },
        "external_id": {
          "type": [
            "string",
            "null"
          ]
        },
        "anonymous": {
          "type": "boolean"
        }
      }
    },
    "binding_id": {
      "type": "string",
      "minLength": 1
    },
    "device_token": {
      "type": "string",
      "minLength": 1
    },
    "native_contract": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "version",
        "capabilities"
      ],
      "properties": {
        "version": {
          "type": "integer",
          "minimum": 0,
          "maximum": 1,
          "enum": [
            0,
            1
          ]
        },
        "capabilities": {
          "type": "array",
          "maxItems": 11,
          "uniqueItems": true,
          "items": {
            "type": "string",
            "enum": [
              "ANDROID_APP_DISPLAY_V1",
              "APNS_DEVICE_TOKEN",
              "DURABLE_SYNC",
              "FCM_FID",
              "FCM_REGISTRATION_TOKEN_LEGACY",
              "FOREGROUND_FORWARD",
              "IDENTITY_HANDOFF",
              "NOTIFICATION_CLICK",
              "PAYLOAD_V1",
              "PERMISSION_OBSERVATION",
              "PUSH_PREFERENCE"
            ]
          }
        }
      }
    }
  }
}
HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

POST /v1/installations/{id}:identify

로그인 — external_id 가 가리키는 사용자로 재바인딩한다

인증: apiKey: identity:write

계약 원문 설명

로그인 — external_id 가 가리키는 사용자로 재바인딩한다

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
id · path필수
{
  "type": "string",
  "pattern": "^[^/:]+$"
}
Kits-Idempotency-Key · header필수
{
  "type": "string",
  "minLength": 1,
  "maxLength": 255,
  "pattern": "^[\\x20-\\x7E]+$"
}

요청 본문

본문 필수

application/json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "external_id",
    "expected_binding_id"
  ],
  "properties": {
    "external_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    },
    "expected_binding_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    }
  }
}

응답

HTTP 200

최초 성공의 status와 모든 불변 결과는 같고 idempotency.replayed만 true로 재생된다

application/json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "app_user",
    "binding_id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    },
    "app_user": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "external_id",
        "anonymous"
      ],
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1
        },
        "external_id": {
          "type": [
            "string",
            "null"
          ]
        },
        "anonymous": {
          "type": "boolean"
        }
      }
    },
    "binding_id": {
      "type": "string",
      "minLength": 1
    }
  }
}
HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

POST /v1/installations/{id}:logout

로그아웃 — 새 익명 사용자로 되돌린다

인증: apiKey: identity:write

계약 원문 설명

로그아웃 — 새 익명 사용자로 되돌린다

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
id · path필수
{
  "type": "string",
  "pattern": "^[^/:]+$"
}
Kits-Idempotency-Key · header필수
{
  "type": "string",
  "minLength": 1,
  "maxLength": 255,
  "pattern": "^[\\x20-\\x7E]+$"
}

요청 본문

본문 필수

application/json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "expected_binding_id"
  ],
  "properties": {
    "expected_binding_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    }
  }
}

응답

HTTP 200

최초 성공의 status와 모든 불변 결과는 같고 idempotency.replayed만 true로 재생된다

application/json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "app_user",
    "binding_id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    },
    "app_user": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "external_id",
        "anonymous"
      ],
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1
        },
        "external_id": {
          "type": [
            "string",
            "null"
          ]
        },
        "anonymous": {
          "type": "boolean"
        }
      }
    },
    "binding_id": {
      "type": "string",
      "minLength": 1
    }
  }
}
HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

POST /v1/installations/{id}:transfer

이미 있는 다른 사용자에게 기기를 이전한다

인증: apiKey: identity:write

계약 원문 설명

이미 있는 다른 사용자에게 기기를 이전한다

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
id · path필수
{
  "type": "string",
  "pattern": "^[^/:]+$"
}
Kits-Idempotency-Key · header필수
{
  "type": "string",
  "minLength": 1,
  "maxLength": 255,
  "pattern": "^[\\x20-\\x7E]+$"
}

요청 본문

본문 필수

application/json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "external_id",
    "expected_binding_id"
  ],
  "properties": {
    "external_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    },
    "expected_binding_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    }
  }
}

응답

HTTP 200

최초 성공의 status와 모든 불변 결과는 같고 idempotency.replayed만 true로 재생된다

application/json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "app_user",
    "binding_id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    },
    "app_user": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "external_id",
        "anonymous"
      ],
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1
        },
        "external_id": {
          "type": [
            "string",
            "null"
          ]
        },
        "anonymous": {
          "type": "boolean"
        }
      }
    },
    "binding_id": {
      "type": "string",
      "minLength": 1
    }
  }
}
HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

GET /v1/app-users/{id}

사용자 현재 상태와 묶인 구독의 bounded keyset page

인증: apiKey: identity:read

계약 원문 설명

사용자 현재 상태와 묶인 구독의 bounded keyset page

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
id · path필수
{
  "type": "string",
  "pattern": "^[^/:]+$"
}
subscription_limit · query선택
{
  "type": "integer",
  "minimum": 1,
  "maximum": 200,
  "default": 50
}
subscription_cursor · query선택
{
  "type": "string",
  "maxLength": 384,
  "pattern": "^[A-Za-z0-9_-]+$"
}

요청 본문

응답

HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 2XX

성공. 정확한 상태 코드와 본문 모양은 계약 문서 §5 를 보라

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

GET /v1/app-users/by-external-id/{external_id}

고객사 식별자로 사용자와 묶인 구독의 bounded keyset page를 찾는다

인증: apiKey: identity:read

계약 원문 설명

고객사 식별자로 사용자와 묶인 구독의 bounded keyset page를 찾는다

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
external_id · path필수
{
  "type": "string",
  "pattern": "^[^/:]+$"
}
subscription_limit · query선택
{
  "type": "integer",
  "minimum": 1,
  "maximum": 200,
  "default": 50
}
subscription_cursor · query선택
{
  "type": "string",
  "maxLength": 384,
  "pattern": "^[A-Za-z0-9_-]+$"
}

요청 본문

응답

HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 2XX

성공. 정확한 상태 코드와 본문 모양은 계약 문서 §5 를 보라

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

POST /v1/push-subscriptions

기기 푸시 주소를 등록한다. 토큰은 봉인해서 저장한다

인증: apiKey: identity:write OR deviceToken: 자기 앱 설치에 한정

계약 원문 설명

기기 푸시 주소를 등록한다. 토큰은 봉인해서 저장한다

경로·쿼리·헤더 입력

이 작업에 별도 선언된 parameter가 없습니다.

요청 본문

본문 필수

application/json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "installation_id",
    "kind",
    "address",
    "provider_environment"
  ],
  "properties": {
    "installation_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    },
    "kind": {
      "type": "string",
      "enum": [
        "IOS_PUSH",
        "ANDROID_PUSH"
      ]
    },
    "address": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type",
        "value"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "FCM_FID",
            "FCM_REGISTRATION_TOKEN_LEGACY",
            "APNS_DEVICE_TOKEN"
          ]
        },
        "value": {
          "type": "string",
          "minLength": 1,
          "maxLength": 256,
          "pattern": "^(?=.*\\S)[^\\u0000-\\u001F\\u007F\"\\\\]+$",
          "x-kits-max-utf8-bytes": 256,
          "description": "공백만인 값은 금지하며 최대 256 UTF-8 byte이고 control·DEL·double quote·backslash는 허용하지 않는다"
        }
      }
    },
    "provider_environment": {
      "type": "string",
      "enum": [
        "SANDBOX",
        "PRODUCTION"
      ]
    }
  },
  "oneOf": [
    {
      "properties": {
        "kind": {
          "const": "ANDROID_PUSH"
        },
        "address": {
          "properties": {
            "type": {
              "enum": [
                "FCM_FID",
                "FCM_REGISTRATION_TOKEN_LEGACY"
              ]
            }
          }
        },
        "provider_environment": {
          "const": "PRODUCTION"
        }
      }
    },
    {
      "properties": {
        "kind": {
          "const": "IOS_PUSH"
        },
        "address": {
          "properties": {
            "type": {
              "const": "APNS_DEVICE_TOKEN"
            }
          }
        },
        "provider_environment": {
          "enum": [
            "SANDBOX",
            "PRODUCTION"
          ]
        }
      }
    }
  ]
}

응답

HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 2XX

새 주소 세대는 201, 현재 주소의 반복 등록은 200이다

application/json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "state",
    "address_generation",
    "identity_verification_state",
    "retired_addresses"
  ],
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^sub_[0-9a-f]{32}$"
    },
    "state": {
      "type": "string",
      "enum": [
        "ACTIVE",
        "INVALIDATED"
      ]
    },
    "address_generation": {
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "identity_verification_state": {
      "type": "string",
      "enum": [
        "UNVERIFIED",
        "VERIFIED",
        "EXPIRED"
      ]
    },
    "retired_addresses": {
      "type": "array",
      "maxItems": 100,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "subscription_id",
          "generation",
          "reason"
        ],
        "properties": {
          "subscription_id": {
            "type": "string",
            "pattern": "^sub_[0-9a-f]{32}$"
          },
          "generation": {
            "type": "integer",
            "minimum": 1,
            "maximum": 9007199254740991
          },
          "reason": {
            "type": "string",
            "enum": [
              "ADDRESS_LIMIT_EXCEEDED",
              "TOKEN_TRANSFERRED"
            ]
          }
        }
      }
    }
  }
}
HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

POST /v1/push-subscriptions:unregister

현재 주소와 정확히 일치할 때만 기기 푸시 주소를 등록 해제한다

인증: apiKey: identity:write OR deviceToken: 자기 앱 설치에 한정

계약 원문 설명

현재 주소와 정확히 일치할 때만 기기 푸시 주소를 등록 해제한다

경로·쿼리·헤더 입력

이 작업에 별도 선언된 parameter가 없습니다.

요청 본문

본문 필수

application/json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "installation_id",
    "kind",
    "address"
  ],
  "properties": {
    "installation_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    },
    "kind": {
      "type": "string",
      "enum": [
        "IOS_PUSH",
        "ANDROID_PUSH"
      ]
    },
    "address": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type",
        "value"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "FCM_FID",
            "FCM_REGISTRATION_TOKEN_LEGACY",
            "APNS_DEVICE_TOKEN"
          ]
        },
        "value": {
          "type": "string",
          "minLength": 1,
          "maxLength": 256,
          "pattern": "^(?=.*\\S)[^\\u0000-\\u001F\\u007F\"\\\\]+$",
          "x-kits-max-utf8-bytes": 256,
          "description": "공백만인 값은 금지하며 최대 256 UTF-8 byte이고 control·DEL·double quote·backslash는 허용하지 않는다"
        }
      }
    }
  },
  "oneOf": [
    {
      "properties": {
        "kind": {
          "const": "ANDROID_PUSH"
        },
        "address": {
          "properties": {
            "type": {
              "enum": [
                "FCM_FID",
                "FCM_REGISTRATION_TOKEN_LEGACY"
              ]
            }
          }
        }
      }
    },
    {
      "properties": {
        "kind": {
          "const": "IOS_PUSH"
        },
        "address": {
          "properties": {
            "type": {
              "const": "APNS_DEVICE_TOKEN"
            }
          }
        }
      }
    }
  ]
}

응답

HTTP 200

일치한 현재 주소를 퇴역시켰는지 여부. stale·duplicate는 false다

application/json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "unregistered"
  ],
  "properties": {
    "unregistered": {
      "type": "boolean"
    }
  }
}
HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

POST /v1/push-subscriptions/{id}/addresses

주소 세대를 회전한다

인증: apiKey: identity:write

계약 원문 설명

주소 세대를 회전한다

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
id · path필수
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

요청 본문

본문 필수

application/json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "address",
    "provider_environment"
  ],
  "properties": {
    "address": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type",
        "value"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "FCM_FID",
            "FCM_REGISTRATION_TOKEN_LEGACY",
            "APNS_DEVICE_TOKEN"
          ]
        },
        "value": {
          "type": "string",
          "minLength": 1,
          "maxLength": 256,
          "pattern": "^(?=.*\\S)[^\\u0000-\\u001F\\u007F\"\\\\]+$",
          "x-kits-max-utf8-bytes": 256,
          "description": "공백만인 값은 금지하며 최대 256 UTF-8 byte이고 control·DEL·double quote·backslash는 허용하지 않는다"
        }
      }
    },
    "provider_environment": {
      "type": "string",
      "enum": [
        "SANDBOX",
        "PRODUCTION"
      ]
    }
  },
  "oneOf": [
    {
      "properties": {
        "address": {
          "properties": {
            "type": {
              "enum": [
                "FCM_FID",
                "FCM_REGISTRATION_TOKEN_LEGACY"
              ]
            }
          }
        },
        "provider_environment": {
          "const": "PRODUCTION"
        }
      }
    },
    {
      "properties": {
        "address": {
          "properties": {
            "type": {
              "const": "APNS_DEVICE_TOKEN"
            }
          }
        },
        "provider_environment": {
          "enum": [
            "SANDBOX",
            "PRODUCTION"
          ]
        }
      }
    }
  ]
}

응답

HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 2XX

새 주소 세대는 201, 현재 주소의 반복 등록은 200이다

application/json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "state",
    "address_generation",
    "identity_verification_state",
    "retired_addresses"
  ],
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^sub_[0-9a-f]{32}$"
    },
    "state": {
      "type": "string",
      "enum": [
        "ACTIVE",
        "INVALIDATED"
      ]
    },
    "address_generation": {
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "identity_verification_state": {
      "type": "string",
      "enum": [
        "UNVERIFIED",
        "VERIFIED",
        "EXPIRED"
      ]
    },
    "retired_addresses": {
      "type": "array",
      "maxItems": 100,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "subscription_id",
          "generation",
          "reason"
        ],
        "properties": {
          "subscription_id": {
            "type": "string",
            "pattern": "^sub_[0-9a-f]{32}$"
          },
          "generation": {
            "type": "integer",
            "minimum": 1,
            "maximum": 9007199254740991
          },
          "reason": {
            "type": "string",
            "enum": [
              "ADDRESS_LIMIT_EXCEEDED",
              "TOKEN_TRANSFERRED"
            ]
          }
        }
      }
    }
  }
}
HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

POST /v1/push-subscriptions/{id}:invalidate

지금 살아 있는 주소 세대를 무효화한다

인증: apiKey: identity:write

계약 원문 설명

지금 살아 있는 주소 세대를 무효화한다

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
id · path필수
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

요청 본문

응답

HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 2XX

성공. 정확한 상태 코드와 본문 모양은 계약 문서 §5 를 보라

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

POST /v1/push-subscriptions/{id}/addresses/{generation}:invalidate

정확히 그 세대만 무효화한다

인증: apiKey: identity:write

계약 원문 설명

정확히 그 세대만 무효화한다

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
id · path필수
{
  "type": "string",
  "pattern": "^[^/:]+$"
}
generation · path필수
{
  "type": "integer",
  "minimum": 1,
  "maximum": 9007199254740991
}

요청 본문

응답

HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 2XX

성공. 정확한 상태 코드와 본문 모양은 계약 문서 §5 를 보라

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

POST /v1/installations/{id}/permission-observations

OS 알림 권한 관측을 기록한다. 고치지 않고 쌓는다

인증: apiKey: consent:write OR deviceToken: 자기 앱 설치에 한정

계약 원문 설명

OS 알림 권한 관측을 기록한다. 고치지 않고 쌓는다

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
id · path필수
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

요청 본문

응답

HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 2XX

성공. 정확한 상태 코드와 본문 모양은 계약 문서 §5 를 보라

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

POST /v1/installations/{id}:set-push-preference

앱 안 알림 설정을 바꾼다

인증: apiKey: consent:write OR deviceToken: 자기 앱 설치에 한정

계약 원문 설명

앱 안 알림 설정을 바꾼다

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
id · path필수
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

요청 본문

응답

HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 2XX

성공. 정확한 상태 코드와 본문 모양은 계약 문서 §5 를 보라

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

POST /v1/app-users/{id}/marketing-consents

마케팅 동의를 기록한다. 철회도 새로 쌓는다

인증: apiKey: consent:write

계약 원문 설명

마케팅 동의를 기록한다. 철회도 새로 쌓는다

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
id · path필수
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

요청 본문

응답

HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 2XX

성공. 정확한 상태 코드와 본문 모양은 계약 문서 §5 를 보라

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

GET /v1/app-users/{id}/marketing-consents

마케팅 동의 이력의 bounded keyset page

인증: apiKey: consent:read

계약 원문 설명

마케팅 동의 이력의 bounded keyset page

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
id · path필수
{
  "type": "string",
  "pattern": "^[^/:]+$"
}
limit · query선택
{
  "type": "integer",
  "minimum": 1,
  "maximum": 200,
  "default": 50
}
cursor · query선택
{
  "type": "string",
  "maxLength": 256,
  "pattern": "^[A-Za-z0-9_-]+$"
}

요청 본문

응답

HTTP 200

현재 상태와 동의 이력 한 쪽

application/json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "app_user_id",
    "current",
    "history",
    "next_cursor"
  ],
  "properties": {
    "app_user_id": {
      "type": "string"
    },
    "current": {
      "oneOf": [
        {
          "type": "null"
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "state",
            "occurred_at"
          ],
          "properties": {
            "state": {
              "type": "string",
              "enum": [
                "GRANTED",
                "WITHDRAWN"
              ]
            },
            "occurred_at": {
              "type": "string",
              "format": "date-time"
            }
          }
        }
      ]
    },
    "history": {
      "type": "array",
      "maxItems": 200,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "state",
          "source",
          "policy_version",
          "actor_type",
          "occurred_at",
          "recorded_at"
        ],
        "properties": {
          "state": {
            "type": "string",
            "enum": [
              "GRANTED",
              "WITHDRAWN"
            ]
          },
          "source": {
            "type": "string"
          },
          "policy_version": {
            "type": [
              "string",
              "null"
            ]
          },
          "actor_type": {
            "type": "string"
          },
          "occurred_at": {
            "type": "string",
            "format": "date-time"
          },
          "recorded_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    },
    "next_cursor": {
      "type": [
        "string",
        "null"
      ]
    }
  }
}
HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

GET /v1/app-users/{id}/delivery-eligibility

지금 이 사람에게 보낼 수 있나, 안 되면 왜

인증: apiKey: messages:read

계약 원문 설명

지금 이 사람에게 보낼 수 있나, 안 되면 왜

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
id · path필수
{
  "type": "string",
  "pattern": "^[^/:]+$"
}
classification · query선택
{
  "type": "string",
  "enum": [
    "SERVICE",
    "PROMOTIONAL"
  ],
  "default": "SERVICE"
}
subscription_state · query선택
{
  "type": "string",
  "enum": [
    "ALL",
    "ACTIVE",
    "INACTIVE"
  ],
  "default": "ALL"
}
limit · query선택
{
  "type": "integer",
  "minimum": 1,
  "maximum": 200
}
cursor · query선택
{
  "type": "string",
  "maxLength": 512,
  "pattern": "^[A-Za-z0-9_-]+$"
}

요청 본문

응답

HTTP 200

현재 구독별 발송 가능성의 bounded page

application/json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "app_user_id",
    "classification",
    "subscription_state",
    "subscriptions",
    "next_cursor",
    "checked",
    "not_checked",
    "withheld"
  ],
  "properties": {
    "app_user_id": {
      "type": "string",
      "pattern": "^usr_[0-9a-f]{32}$"
    },
    "classification": {
      "type": "string",
      "enum": [
        "SERVICE",
        "PROMOTIONAL"
      ]
    },
    "subscription_state": {
      "type": "string",
      "enum": [
        "ALL",
        "ACTIVE",
        "INACTIVE"
      ]
    },
    "subscriptions": {
      "type": "array",
      "maxItems": 1000,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "eligible"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^sub_[0-9a-f]{32}$"
          },
          "eligible": {
            "type": "boolean"
          },
          "blocked_by": {
            "type": "string",
            "enum": [
              "ADDRESS_INVALID",
              "NATIVE_CAPABILITY_MISSING",
              "OS_PERMISSION_MISSING",
              "APP_OPTED_OUT",
              "MARKETING_CONSENT_MISSING"
            ]
          },
          "permission_state": {
            "type": "string",
            "enum": [
              "NOT_DETERMINED",
              "AUTHORIZED",
              "DENIED",
              "PROVISIONAL",
              "EPHEMERAL"
            ]
          },
          "observed_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    },
    "next_cursor": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 512,
      "pattern": "^[A-Za-z0-9_-]+$"
    },
    "marketing_consent": {
      "oneOf": [
        {
          "type": "null"
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "state",
            "occurred_at"
          ],
          "properties": {
            "state": {
              "type": "string",
              "enum": [
                "GRANTED",
                "WITHDRAWN"
              ]
            },
            "occurred_at": {
              "type": "string",
              "format": "date-time"
            }
          }
        }
      ]
    },
    "checked": {
      "type": "array",
      "maxItems": 6,
      "items": {
        "type": "string",
        "enum": [
          "SUBSCRIPTION_ACTIVE",
          "ADDRESS_PRESENT",
          "NATIVE_CAPABILITY",
          "OS_PERMISSION",
          "APP_PREFERENCE",
          "MARKETING_CONSENT"
        ]
      }
    },
    "not_checked": {
      "type": "array",
      "maxItems": 4,
      "items": {
        "type": "string",
        "enum": [
          "IDENTITY_CHANGED",
          "MESSAGE_EXPIRED",
          "DISPATCH_PAUSED",
          "RETRY_BUDGET_EXHAUSTED"
        ]
      }
    },
    "withheld": {
      "type": "array",
      "maxItems": 2,
      "items": {
        "type": "string",
        "enum": [
          "MARKETING_CONSENT",
          "OS_PERMISSION"
        ]
      }
    }
  }
}
HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

POST /v1/messages

발송 접수. 한 사람 또는 여러 사람(최대 20000). 실제 전송은 워커가 한다

인증: apiKey: messages:send

계약 원문 설명

발송 접수. 한 사람 또는 여러 사람(최대 20000). 실제 전송은 워커가 한다

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
Kits-Idempotency-Key · header필수
{
  "type": "string",
  "minLength": 1,
  "maxLength": 255,
  "pattern": "^[\\x20-\\x7E]+$"
}

요청 본문

본문 필수

application/json

{
  "$ref": "#/components/schemas/MessageRequest"
}

공통 스키마: MessageRequest

응답

HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 2XX

성공. 정확한 상태 코드와 본문 모양은 계약 문서 §5 를 보라

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

POST /v1/broadcasts

이 앱의 모두에게 발송. 대상 행은 뒤에서 만들어진다

인증: apiKey: broadcasts:send

계약 원문 설명

이 앱의 모두에게 발송. 대상 행은 뒤에서 만들어진다

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
Kits-Idempotency-Key · header필수
{
  "type": "string",
  "minLength": 1,
  "maxLength": 255,
  "pattern": "^[\\x20-\\x7E]+$"
}

요청 본문

응답

HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 2XX

성공. 정확한 상태 코드와 본문 모양은 계약 문서 §5 를 보라

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

GET /v1/messages/{id}

요청 단위 결과 요약

인증: apiKey: messages:read

계약 원문 설명

요청 단위 결과 요약

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
id · path필수
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

요청 본문

응답

HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 2XX

성공. 정확한 상태 코드와 본문 모양은 계약 문서 §5 를 보라

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

GET /v1/messages/{id}/deliveries

대상별 결과

인증: apiKey: messages:read

계약 원문 설명

대상별 결과

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
id · path필수
{
  "type": "string",
  "pattern": "^[^/:]+$"
}
limit · query선택
{
  "type": "integer",
  "minimum": 1,
  "maximum": 200
}
cursor · query선택
{
  "type": "string",
  "maxLength": 1024,
  "pattern": "^[A-Za-z0-9_-]+$"
}

요청 본문

응답

HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 2XX

성공. 정확한 상태 코드와 본문 모양은 계약 문서 §5 를 보라

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

GET /v1/deliveries

사람이 닫아야 하는 미결 발송 목록

인증: apiKey: dispatch-control:read

계약 원문 설명

사람이 닫아야 하는 미결 발송 목록

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
state · query필수
{
  "type": "string",
  "enum": [
    "OUTCOME_UNKNOWN"
  ]
}
limit · query선택
{
  "type": "integer",
  "minimum": 1,
  "maximum": 200,
  "default": 50
}
cursor · query선택
{
  "type": "string",
  "maxLength": 256,
  "pattern": "^[A-Za-z0-9_-]+$"
}

요청 본문

응답

HTTP 200

미결 발송 한 쪽과 10,000건 상한의 queue 크기

application/json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "items",
    "next_cursor",
    "total",
    "total_exact"
  ],
  "properties": {
    "items": {
      "type": "array",
      "maxItems": 200,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "message_id",
          "subscription_id",
          "classification",
          "attempt_count",
          "created_at"
        ],
        "properties": {
          "message_id": {
            "type": "string",
            "pattern": "^msg_[A-Za-z0-9_-]{24}$"
          },
          "subscription_id": {
            "type": "string",
            "pattern": "^sub_[0-9a-f]{32}$"
          },
          "classification": {
            "type": "string",
            "enum": [
              "SERVICE",
              "PROMOTIONAL"
            ]
          },
          "attempt_count": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2147483647
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "provider_status": {
            "type": "integer",
            "minimum": 100,
            "maximum": 599
          },
          "provider_code": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64,
            "description": "authoritative provider와 HTTP status에 결속된 customer-safe code"
          }
        }
      }
    },
    "next_cursor": {
      "oneOf": [
        {
          "type": "string",
          "maxLength": 256,
          "pattern": "^[A-Za-z0-9_-]+$"
        },
        {
          "type": "null"
        }
      ]
    },
    "total": {
      "type": "integer",
      "minimum": 0,
      "maximum": 10000
    },
    "total_exact": {
      "type": "boolean",
      "description": "false면 total은 정확한 합계가 아니라 최소 10,000건이라는 하한"
    }
  }
}
HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

POST /v1/messages/{id}:stop

이 메시지의 남은 발송을 멈춘다. 앱 전체를 끄지 않고

인증: apiKey: dispatch-control:write

계약 원문 설명

이 메시지의 남은 발송을 멈춘다. 앱 전체를 끄지 않고

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
id · path필수
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

요청 본문

응답

HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 2XX

성공. 정확한 상태 코드와 본문 모양은 계약 문서 §5 를 보라

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

POST /v1/messages/{id}/deliveries/{subscription_id}:resolve-unknown

결과불명 발송을 운영자가 수동으로 종결한다

인증: apiKey: dispatch-control:write

계약 원문 설명

결과불명 발송을 운영자가 수동으로 종결한다

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
id · path필수
{
  "type": "string",
  "pattern": "^[^/:]+$"
}
subscription_id · path필수
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

요청 본문

응답

HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 2XX

성공. 정확한 상태 코드와 본문 모양은 계약 문서 §5 를 보라

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

GET /v1/app-environments/{id}/dispatch-control

지금 멈춰 있는가와 현재 제어 세대

인증: apiKey: dispatch-control:read

계약 원문 설명

지금 멈춰 있는가와 현재 제어 세대

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
id · path필수
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

요청 본문

응답

HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 2XX

성공. 정확한 상태 코드와 본문 모양은 계약 문서 §5 를 보라

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

GET /v1/app-environments/{id}/address-breaker

주소 대량 삭제 차단기가 걸려 있는가와 걸린 근거

인증: apiKey: dispatch-control:read

계약 원문 설명

주소 대량 삭제 차단기가 걸려 있는가와 걸린 근거

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
id · path필수
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

요청 본문

응답

HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 2XX

성공. 정확한 상태 코드와 본문 모양은 계약 문서 §5 를 보라

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

POST /v1/app-environments/{id}:reset-address-breaker

차단기를 푼다. 대량 주소 삭제를 다시 켜는 일이라 사유가 필요하다

인증: apiKey: dispatch-control:write

계약 원문 설명

차단기를 푼다. 대량 주소 삭제를 다시 켜는 일이라 사유가 필요하다

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
id · path필수
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

요청 본문

응답

HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 2XX

성공. 정확한 상태 코드와 본문 모양은 계약 문서 §5 를 보라

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

POST /v1/app-environments/{id}:pause-dispatch

긴급 정지. 세대를 올려 대기 중인 것도 막는다

인증: apiKey: dispatch-control:write

계약 원문 설명

긴급 정지. 세대를 올려 대기 중인 것도 막는다

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
id · path필수
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

요청 본문

응답

HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 2XX

성공. 정확한 상태 코드와 본문 모양은 계약 문서 §5 를 보라

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

POST /v1/app-environments/{id}:resume-dispatch

발송 재개

인증: apiKey: dispatch-control:write

계약 원문 설명

발송 재개

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
id · path필수
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

요청 본문

응답

HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 2XX

성공. 정확한 상태 코드와 본문 모양은 계약 문서 §5 를 보라

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

POST /v1/push-provider-connections

공급자 자격증명을 등록한다. 원문은 봉인되어 저장된다

인증: apiKey: provider-connections:write

계약 원문 설명

공급자 자격증명을 등록한다. 원문은 봉인되어 저장된다

경로·쿼리·헤더 입력

이 작업에 별도 선언된 parameter가 없습니다.

요청 본문

응답

HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 2XX

성공. 정확한 상태 코드와 본문 모양은 계약 문서 §5 를 보라

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

GET /v1/push-provider-connections

연결 health와 최신 후보·실제 active 버전·dispatch readiness를 조회한다

인증: apiKey: provider-connections:read

계약 원문 설명

연결 health와 최신 후보·실제 active 버전·dispatch readiness를 조회한다

경로·쿼리·헤더 입력

이 작업에 별도 선언된 parameter가 없습니다.

요청 본문

응답

HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 2XX

성공. 정확한 상태 코드와 본문 모양은 계약 문서 §5 를 보라

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

POST /v1/push-provider-connections/{id}:rotate-credential

PENDING 후보 버전을 더한다. 검증 PASS 전까지 기존 active로 계속 발송한다

인증: apiKey: credentials:rotate

계약 원문 설명

PENDING 후보 버전을 더한다. 검증 PASS 전까지 기존 active로 계속 발송한다

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
id · path필수
{
  "type": "string",
  "pattern": "^[^/:]+$"
}
Kits-Idempotency-Key · header필수
{
  "type": "string",
  "minLength": 1,
  "maxLength": 255,
  "pattern": "^[\\x20-\\x7E]+$"
}

요청 본문

응답

HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 2XX

성공. 정확한 상태 코드와 본문 모양은 계약 문서 §5 를 보라

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

POST /v1/push-provider-connections/{id}:recover-credential

기존 active 키의 신원을 복원할 수 없는 터미널 상태에서만 명시적 복구 후보를 생성한다

인증: apiKey: credentials:rotate

계약 원문 설명

기존 active 키의 신원을 복원할 수 없는 터미널 상태에서만 명시적 복구 후보를 생성한다

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
id · path필수
{
  "type": "string",
  "pattern": "^[^/:]+$"
}
Kits-Idempotency-Key · header필수
{
  "type": "string",
  "minLength": 1,
  "maxLength": 255,
  "pattern": "^[\\x20-\\x7E]+$"
}

요청 본문

응답

HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 2XX

성공. 정확한 상태 코드와 본문 모양은 계약 문서 §5 를 보라

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

POST /v1/push-provider-connections/{id}:verify

다시 확인해 달라고 요청한다. 확인은 워커가 한다

인증: apiKey: provider-connections:write

계약 원문 설명

다시 확인해 달라고 요청한다. 확인은 워커가 한다

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
id · path필수
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

요청 본문

응답

HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 2XX

성공. 정확한 상태 코드와 본문 모양은 계약 문서 §5 를 보라

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

PUT /v1/attribute-definitions/{key}

속성 키와 타입을 등록한다

인증: apiKey: attributes:write

계약 원문 설명

속성 키와 타입을 등록한다

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
key · path필수
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

요청 본문

응답

HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 2XX

성공. 정확한 상태 코드와 본문 모양은 계약 문서 §5 를 보라

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

GET /v1/attribute-definitions

등록된 속성 정의의 bounded keyset 목록

인증: apiKey: attributes:read

계약 원문 설명

등록된 속성 정의의 bounded keyset 목록

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
limit · query선택
{
  "type": "integer",
  "minimum": 1,
  "maximum": 200,
  "default": 50
}
cursor · query선택
{
  "type": "string",
  "maxLength": 256,
  "pattern": "^[A-Za-z0-9_-]+$"
}

요청 본문

응답

HTTP 200

속성 정의 한 쪽

application/json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "data",
    "next_cursor"
  ],
  "properties": {
    "data": {
      "type": "array",
      "maxItems": 200,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "key",
          "value_type",
          "created_at",
          "retired_at"
        ],
        "properties": {
          "key": {
            "type": "string",
            "pattern": "^[A-Za-z][A-Za-z0-9_]{0,62}$"
          },
          "value_type": {
            "type": "string",
            "enum": [
              "STRING",
              "NUMBER",
              "BOOLEAN",
              "DATETIME",
              "STRING_SET"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "retired_at": {
            "oneOf": [
              {
                "type": "string",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      }
    },
    "next_cursor": {
      "oneOf": [
        {
          "type": "string",
          "maxLength": 256,
          "pattern": "^[A-Za-z0-9_-]+$"
        },
        {
          "type": "null"
        }
      ]
    }
  }
}
HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

POST /v1/app-users/{id}:set-attributes

속성 값을 기록한다. 더 새로운 관측만 이긴다

인증: apiKey: attributes:write

계약 원문 설명

속성 값을 기록한다. 더 새로운 관측만 이긴다

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
id · path필수
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

요청 본문

응답

HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 2XX

성공. 정확한 상태 코드와 본문 모양은 계약 문서 §5 를 보라

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

PUT /v1/event-definitions/{name}

이벤트 이름을 등록한다

인증: apiKey: events:write

계약 원문 설명

이벤트 이름을 등록한다

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
name · path필수
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

요청 본문

응답

HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 2XX

성공. 정확한 상태 코드와 본문 모양은 계약 문서 §5 를 보라

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

GET /v1/event-definitions

등록된 이벤트 정의의 bounded keyset 목록

인증: apiKey: events:read

계약 원문 설명

등록된 이벤트 정의의 bounded keyset 목록

경로·쿼리·헤더 입력

이름 / 위치필수형식과 범위
limit · query선택
{
  "type": "integer",
  "minimum": 1,
  "maximum": 200,
  "default": 50
}
cursor · query선택
{
  "type": "string",
  "maxLength": 256,
  "pattern": "^[A-Za-z0-9_-]+$"
}

요청 본문

응답

HTTP 200

이벤트 정의 한 쪽

application/json

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "data",
    "next_cursor"
  ],
  "properties": {
    "data": {
      "type": "array",
      "maxItems": 200,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "name",
          "created_at",
          "retired_at"
        ],
        "properties": {
          "name": {
            "type": "string",
            "pattern": "^[A-Za-z][A-Za-z0-9_]{0,62}$"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "retired_at": {
            "oneOf": [
              {
                "type": "string",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      }
    },
    "next_cursor": {
      "oneOf": [
        {
          "type": "string",
          "maxLength": 256,
          "pattern": "^[A-Za-z0-9_-]+$"
        },
        {
          "type": "null"
        }
      ]
    }
  }
}
HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

POST /v1/app-events

이벤트를 배치로 기록한다. 클라이언트 id 로 중복을 거른다

인증: apiKey: events:write

계약 원문 설명

이벤트를 배치로 기록한다. 클라이언트 id 로 중복을 거른다

경로·쿼리·헤더 입력

이 작업에 별도 선언된 parameter가 없습니다.

요청 본문

응답

HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 2XX

성공. 정확한 상태 코드와 본문 모양은 계약 문서 §5 를 보라

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

GET /v1/registry/enums

상태값 레지스트리 전체

인증: apiKey: 인증 필요, 별도 권한 없음

계약 원문 설명

상태값 레지스트리 전체

경로·쿼리·헤더 입력

이 작업에 별도 선언된 parameter가 없습니다.

요청 본문

응답

HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 2XX

성공

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

GET /v1/registry/error-codes

오류 코드 레지스트리 전체

인증: apiKey: 인증 필요, 별도 권한 없음

계약 원문 설명

오류 코드 레지스트리 전체

경로·쿼리·헤더 입력

이 작업에 별도 선언된 parameter가 없습니다.

요청 본문

응답

HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 2XX

성공

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

GET /v1/registry/message-fields

메시지 필드 레지스트리 전체

인증: apiKey: 인증 필요, 별도 권한 없음

계약 원문 설명

메시지 필드 레지스트리 전체

경로·쿼리·헤더 입력

이 작업에 별도 선언된 parameter가 없습니다.

요청 본문

응답

HTTP 401

Bearer credential이 없거나 유효하지 않다

응답 헤더

{
  "WWW-Authenticate": {
    "required": true,
    "description": "구체적인 credential 상태를 노출하지 않는 Bearer challenge",
    "schema": {
      "type": "string",
      "const": "Bearer"
    }
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 2XX

성공

HTTP 4XX

요청이 거절됐다

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

HTTP 5XX

우리 쪽 오류

응답 헤더

{
  "Retry-After": {
    "$ref": "#/components/headers/OptionalRetryAfter"
  }
}

application/json

{
  "$ref": "#/components/schemas/Error"
}

공통 스키마: Error

공통 JSON Schema

$ref가 가리키는 공통 정의입니다. 설명 문자열은 원문이며, 필드·필수값·제약은 기계 판독 가능한 계약입니다.

Error

스키마 펼치기
{
  "type": "object",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "object",
      "required": [
        "code",
        "message",
        "request_id",
        "retryable",
        "field_errors",
        "docs_url"
      ],
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "UNAUTHENTICATED",
            "PERMISSION_DENIED",
            "RESOURCE_NOT_FOUND",
            "IDEMPOTENCY_KEY_REUSED",
            "IDEMPOTENCY_IN_PROGRESS",
            "IDENTITY_REBIND_CONFLICT",
            "IDENTITY_REBIND_IN_PROGRESS",
            "DELIVERY_NOT_RESOLVABLE",
            "DISPATCH_CONTROL_STALE",
            "PROVIDER_CONNECTION_EXISTS",
            "PROVIDER_CREDENTIAL_IDENTITY_PENDING",
            "PROVIDER_CREDENTIAL_RECOVERY_REQUIRED",
            "PROVIDER_CREDENTIAL_RECOVERY_NOT_REQUIRED",
            "PROVIDER_CREDENTIAL_RECOVERY_IN_PROGRESS",
            "MALFORMED_REQUEST",
            "FIELD_REQUIRED",
            "METHOD_NOT_ALLOWED",
            "REQUEST_TOO_LARGE",
            "PAYLOAD_TOO_LARGE",
            "RESERVED_DATA_KEY",
            "UNKNOWN_FIELD",
            "FIELD_TYPE_MISMATCH",
            "ATTRIBUTE_KEY_NOT_REGISTERED",
            "EVENT_NAME_NOT_REGISTERED",
            "DEFINITION_LIMIT_EXCEEDED",
            "INSTALLATION_LIMIT_EXCEEDED",
            "RESERVED_NAMESPACE",
            "PROVIDER_CREDENTIAL_INVALID",
            "PROVIDER_ENVIRONMENT_MISMATCH",
            "RATE_LIMITED",
            "INTERNAL_ERROR",
            "DISPATCH_PAUSED",
            "RESOURCE_ARCHIVED"
          ]
        },
        "message": {
          "type": "string"
        },
        "request_id": {
          "type": "string"
        },
        "retryable": {
          "type": "boolean"
        },
        "field_errors": {
          "type": "array",
          "maxItems": 100,
          "items": {
            "$ref": "#/components/schemas/FieldError"
          }
        },
        "docs_url": {
          "type": "string",
          "format": "uri"
        }
      }
    }
  }
}

공통 스키마: FieldError

FieldError

스키마 펼치기
{
  "type": "object",
  "required": [
    "field",
    "code",
    "message"
  ],
  "properties": {
    "field": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    },
    "code": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "message": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500
    }
  }
}

MessageRequest

스키마 펼치기
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "target",
    "classification",
    "title",
    "body"
  ],
  "properties": {
    "send_purpose": {
      "type": "string",
      "enum": [
        "STANDARD",
        "TEST"
      ],
      "default": "STANDARD",
      "description": "Admission metadata, not a notification payload field. TEST sends real pushes with unchanged authorization and consent rules. Included in the idempotent intent; omitted and STANDARD are equivalent."
    },
    "personalize": {
      "type": "boolean",
      "default": false,
      "description": "명시적으로 켠 경우에만 제목·본문·부제의 {{user.key|기본값}} 또는 {{tag.key|기본값}}을 delivery 생성 시 치환하고 고정한다 (REQ-MSG-002)"
    },
    "track_receipts": {
      "type": "boolean",
      "default": false,
      "description": "track_events와 함께 켠 경우 iOS NSE의 제한된 수신 확인 capability를 추가한다. 실제 표시 증명이 아니다 (REQ-MSG-003)"
    },
    "track_events": {
      "type": "boolean",
      "default": false,
      "description": "이 메시지의 실제 SDK 수신·클릭 기록을 허용한다. SDK 수집 설정과 저장된 거부를 따르며 실제 표시나 전달을 보장하지 않는다 (REQ-MSG-003)"
    },
    "target": {
      "oneOf": [
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "external_id"
          ],
          "properties": {
            "external_id": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "external_ids"
          ],
          "properties": {
            "external_ids": {
              "type": "array",
              "minItems": 1,
              "maxItems": 20000,
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 255
              }
            }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "installation_id"
          ],
          "properties": {
            "installation_id": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            }
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "subscription_id"
          ],
          "properties": {
            "subscription_id": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            }
          }
        }
      ],
      "description": "누구에게 보내는가. external_id · external_ids(최대 20000) · installation_id · subscription_id 중 하나 (REQ-MSG-001)"
    },
    "classification": {
      "$ref": "#/components/schemas/MessageClassification",
      "description": "서비스 알림인가 마케팅인가. PROMOTIONAL 은 마케팅 동의를 요구한다 (REQ-MSG-003)"
    },
    "display_path": {
      "type": "string",
      "enum": [
        "OS_DISPLAY"
      ],
      "default": "OS_DISPLAY",
      "description": "OS 가 띄우는가 앱이 띄우는가. v1a 는 OS_DISPLAY 만 (REQ-MSG-007)"
    },
    "priority": {
      "$ref": "#/components/schemas/MessagePriority",
      "default": "NORMAL",
      "description": "provider 에게 전달하는 우선순위 (REQ-MSG-004)"
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "알림 제목 (REQ-MSG-002)"
    },
    "body": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1000,
      "description": "알림 본문 (REQ-MSG-002)"
    },
    "default_language": {
      "type": "string",
      "maxLength": 35,
      "pattern": "^[a-z]{2,3}(?:-[A-Z][a-z]{3})?(?:-[A-Z]{2}|-[0-9]{3})?$",
      "description": "기본 제목과 본문의 언어. 생략하면 언어와 무관한 기본 문구로 사용한다 (REQ-MSG-002)"
    },
    "localizations": {
      "type": "object",
      "minProperties": 1,
      "description": "언어별 제목·본문·선택적 iOS 부제. 개수 상한 없이 전체 메시지 64 KiB 및 언어별 발송 용량 제한을 적용한다. 정확한 locale → language → 기본 문구 순서로 선택하고 delivery 생성 시 고정한다 (REQ-MSG-002)",
      "propertyNames": {
        "type": "string",
        "maxLength": 35,
        "pattern": "^[a-z]{2,3}(?:-[A-Z][a-z]{3})?(?:-[A-Z]{2}|-[0-9]{3})?$"
      },
      "additionalProperties": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "title",
          "body"
        ],
        "properties": {
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "body": {
            "type": "string",
            "minLength": 1,
            "maxLength": 1000
          },
          "ios_subtitle": {
            "type": "string",
            "maxLength": 200
          }
        }
      }
    },
    "data": {
      "type": "object",
      "additionalProperties": {
        "type": "string",
        "maxLength": 4096
      },
      "maxProperties": 32,
      "propertyNames": {
        "minLength": 1,
        "maxLength": 128
      },
      "description": "앱에 그대로 전달되는 문자열 지도. 키는 1~128자, 값은 최대 4096자이며 provider 예약어는 거부한다 (REQ-MSG-002)"
    },
    "deeplink": {
      "type": "string",
      "maxLength": 2048,
      "description": "알림을 눌렀을 때 열 위치 (REQ-MSG-002)"
    },
    "image_url": {
      "type": "string",
      "maxLength": 2048,
      "format": "uri",
      "pattern": "^[Hh][Tt][Tt][Pp][Ss]?:",
      "description": "알림 이미지 URL. iOS는 앱에 Notification Service Extension 연동 필요 (REQ-MSG-005)"
    },
    "ttl_seconds": {
      "type": "integer",
      "minimum": 0,
      "maximum": 2419200,
      "default": 86400,
      "description": "provider 가 알림을 보관할 시간(초). 0 은 저장하지 말고 한 번만 시도한다 (REQ-MSG-005)"
    },
    "collapse_key": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "pattern": "^[!-~]+$",
      "description": "공백 없는 printable ASCII 식별자. 같은 값의 이전 알림을 대체하며 FCM 은 동시에 4개까지만 유효하다 (REQ-MSG-005)"
    },
    "ios_subtitle": {
      "type": "string",
      "maxLength": 200,
      "description": "aps.alert.subtitle. 제목과 본문 사이에 뜬다 (REQ-MSG-005)"
    },
    "ios_badge": {
      "type": "integer",
      "minimum": 0,
      "maximum": 999999,
      "description": "aps.badge. 절대값이며 0 은 배지 제거다. 증감 연산은 v1 에 없다 (REQ-MSG-005)"
    },
    "ios_sound": {
      "type": "string",
      "maxLength": 200,
      "description": "aps.sound. \"default\" 이거나 앱 번들의 사운드 파일 이름 (REQ-MSG-005)"
    },
    "ios_thread_id": {
      "type": "string",
      "maxLength": 200,
      "description": "aps.thread-id. 같은 값끼리 알림이 묶인다 (REQ-MSG-005)"
    },
    "ios_category": {
      "type": "string",
      "maxLength": 200,
      "description": "aps.category. 액션 버튼용이며 앱에 카테고리 등록이 필요하다 (REQ-MSG-005)"
    },
    "ios_interruption_level": {
      "$ref": "#/components/schemas/IosInterruptionLevel",
      "description": "aps.interruption-level. critical 은 애플의 별도 승인이 필요하다 (REQ-MSG-005)"
    },
    "ios_relevance_score": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "description": "aps.relevance-score. 알림 요약에서 대표로 뽑을 알림을 정한다 (REQ-MSG-005)"
    },
    "android_channel_id": {
      "type": "string",
      "maxLength": 200,
      "description": "android.notification.channel_id. 앱에 채널 등록이 필요하다 (REQ-MSG-005)"
    },
    "android_notification_tag": {
      "type": "string",
      "maxLength": 200,
      "description": "android.notification.tag. 같은 태그의 기존 알림을 교체한다 (REQ-MSG-005)"
    },
    "android_group": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "pattern": "^(?=.*[^\\p{Z}\\u0009-\\u000d\\u001c-\\u0020])[^\\u0000-\\u001f\\u007f-\\u009f]+$",
      "description": "Android SDK 알림 묶음 ID. 같은 값의 개별 알림을 유지하며 요약으로 묶는다. APP_DISPLAY 지원 SDK에서 클라이언트의 데이터 필드 설정보다 우선하며 알림 태그 교체나 채널 설정과는 다르다 (REQ-MSG-005)"
    },
    "android_color": {
      "type": "string",
      "minLength": 7,
      "maxLength": 7,
      "pattern": "^#[0-9a-fA-F]{6}$",
      "description": "android.notification.color. #rrggbb 형식만 받는다 (REQ-MSG-005)"
    },
    "android_small_icon": {
      "type": "string",
      "maxLength": 200,
      "description": "android.notification.icon. 앱 리소스 이름이며 URL 은 쓸 수 없다 (REQ-MSG-005)"
    },
    "android_sound": {
      "type": "string",
      "maxLength": 200,
      "description": "android.notification.sound. \"default\" 이거나 앱에 번들된 파일 이름 (REQ-MSG-005)"
    },
    "android_visibility": {
      "$ref": "#/components/schemas/AndroidVisibility",
      "description": "android.notification.visibility. 잠금화면 노출 범위 (REQ-MSG-005)"
    }
  },
  "allOf": [
    {
      "if": {
        "properties": {
          "classification": {
            "const": "PROMOTIONAL"
          }
        },
        "required": [
          "classification"
        ]
      },
      "then": {
        "required": [
          "display_path"
        ]
      }
    }
  ]
}

공통 스키마: AndroidVisibility · IosInterruptionLevel · MessageClassification · MessagePriority

SubscriptionKind

스키마 펼치기
{
  "type": "string",
  "enum": [
    "IOS_PUSH",
    "ANDROID_PUSH"
  ],
  "description": "REQ-ID-009"
}

SubscriptionState

스키마 펼치기
{
  "type": "string",
  "enum": [
    "ACTIVE",
    "INVALIDATED"
  ],
  "description": "REQ-ID-005, REQ-DLV-006"
}

AddressState

스키마 펼치기
{
  "type": "string",
  "enum": [
    "ACTIVE",
    "SUPERSEDED",
    "INVALIDATED",
    "RETIRED"
  ],
  "description": "REQ-ID-012"
}

AddressType

스키마 펼치기
{
  "type": "string",
  "enum": [
    "FCM_FID",
    "FCM_REGISTRATION_TOKEN_LEGACY",
    "APNS_DEVICE_TOKEN"
  ],
  "description": "REQ-ID-012"
}

CredentialVerificationState

스키마 펼치기
{
  "type": "string",
  "enum": [
    "PENDING",
    "PROPAGATING",
    "VERIFIED",
    "DEGRADED",
    "FAILED"
  ],
  "description": "REQ-PRV-003"
}

CredentialVerificationReason

스키마 펼치기
{
  "type": "string",
  "enum": [
    "OK",
    "MALFORMED_CREDENTIAL",
    "KEY_ID_TEAM_ID_SWAPPED",
    "PROJECT_MISMATCH",
    "AUTHENTICATION_REJECTED",
    "PROPAGATION_PENDING",
    "PROVIDER_UNREACHABLE",
    "DUPLICATE_ACTIVE_PRIVATE_KEY",
    "CREDENTIAL_KEY_IDENTITY_MISMATCH"
  ],
  "description": "REQ-PRV-003"
}

EligibilityResult

스키마 펼치기
{
  "type": "string",
  "enum": [
    "ELIGIBLE",
    "NOT_FOUND",
    "NOT_AUTHORIZED",
    "SUPPRESSED"
  ],
  "description": "REQ-CS-005"
}

IdentityVerificationState

스키마 펼치기
{
  "type": "string",
  "enum": [
    "UNVERIFIED",
    "VERIFIED",
    "EXPIRED"
  ],
  "description": "REQ-ID-008"
}

OsPermissionState

스키마 펼치기
{
  "type": "string",
  "enum": [
    "NOT_DETERMINED",
    "AUTHORIZED",
    "DENIED",
    "PROVISIONAL",
    "EPHEMERAL"
  ],
  "description": "REQ-CS-001"
}

PushPreference

스키마 펼치기
{
  "type": "string",
  "enum": [
    "OPTED_IN",
    "OPTED_OUT"
  ],
  "description": "REQ-CS-002"
}

MarketingConsentState

스키마 펼치기
{
  "type": "string",
  "enum": [
    "GRANTED",
    "WITHDRAWN",
    "UNKNOWN"
  ],
  "description": "REQ-CS-003"
}

MessageClassification

스키마 펼치기
{
  "type": "string",
  "enum": [
    "SERVICE",
    "PROMOTIONAL"
  ],
  "description": "REQ-CS-004"
}

MessagePriority

스키마 펼치기
{
  "type": "string",
  "enum": [
    "NORMAL",
    "HIGH"
  ],
  "description": "REQ-MSG-006"
}

DisplayPath

스키마 펼치기
{
  "type": "string",
  "enum": [
    "OS_DISPLAY",
    "APP_DISPLAY"
  ],
  "description": "REQ-MSG-006"
}

MessageOrigin

스키마 펼치기
{
  "type": "string",
  "enum": [
    "TRANSACTIONAL_API",
    "DASHBOARD_BROADCAST"
  ],
  "description": "REQ-MSG-001"
}

DeliveryState

스키마 펼치기
{
  "type": "string",
  "enum": [
    "PENDING",
    "READY",
    "LEASED",
    "IN_FLIGHT",
    "RETRY_SCHEDULED",
    "ACCEPTED",
    "REJECTED_PERMANENT",
    "OUTCOME_UNKNOWN",
    "SUPPRESSED"
  ],
  "description": "REQ-MSG-012"
}

SuppressionReason

스키마 펼치기
{
  "type": "string",
  "enum": [
    "HIERARCHY_ARCHIVED",
    "MESSAGE_STOPPED",
    "ADDRESS_INVALID",
    "NATIVE_CAPABILITY_MISSING",
    "IDENTITY_CHANGED",
    "OS_PERMISSION_MISSING",
    "APP_OPTED_OUT",
    "MARKETING_CONSENT_MISSING",
    "MESSAGE_EXPIRED",
    "DISPATCH_PAUSED"
  ],
  "description": "REQ-CS-005"
}

FailureClass

스키마 펼치기
{
  "type": "string",
  "enum": [
    "ADDRESS_PERMANENTLY_INVALID",
    "CREDENTIAL_PROBLEM",
    "REQUEST_ERROR",
    "TRANSIENT",
    "OUTCOME_UNKNOWN",
    "PRECONDITION_STALE",
    "RETRY_BUDGET_EXHAUSTED"
  ],
  "description": "REQ-DLV-005"
}

IosInterruptionLevel

스키마 펼치기
{
  "type": "string",
  "enum": [
    "passive",
    "active",
    "time-sensitive",
    "critical"
  ],
  "description": "REQ-MSG-005"
}

AndroidVisibility

스키마 펼치기
{
  "type": "string",
  "enum": [
    "PUBLIC",
    "PRIVATE",
    "SECRET"
  ],
  "description": "REQ-MSG-005"
}

MetricAvailability

스키마 펼치기
{
  "type": "string",
  "enum": [
    "MEASURED",
    "NOT_MEASURABLE"
  ],
  "description": "REQ-DLV-002"
}

AddressInvalidationReason

스키마 펼치기
{
  "type": "string",
  "enum": [
    "ADDRESS_PERMANENTLY_INVALID",
    "OPERATOR_REVOKED"
  ],
  "description": "REQ-DLV-005"
}

IdempotencyOperation

스키마 펼치기
{
  "type": "string",
  "enum": [
    "messages.send",
    "broadcasts.send",
    "installations.register",
    "addresses.register",
    "identity.rebind",
    "consent.record",
    "events.ingest",
    "attributes.set",
    "provider-credentials.rotate",
    "provider-credentials.recover"
  ],
  "description": "REQ-MSG-010"
}