Developer docs

PUSH API · v1a

API reference

Generated with cross-checks between public OpenAPI and endpoints.yaml. There are no execution buttons. Read JSON Schema required fields, enums, oneOf alternatives and bounds together.

Download OpenAPI 3.1 JSON · v1a

RequestOperation
POST /v1/project-messagesSubmit a message to selected apps with a unified server key
GET /v1/project-messages/{id}Read a unified message acceptance receipt (24 hours)
GET /v1/installations/{installation_id}/notification-channelsRead Android notification channel settings
POST /v1/identity-tokensIssue a legacy kitid1 native login proof
GET /v1/installations/{id}/identityRead the current installation identity binding
POST /v1/installations/{id}/identityLog an installation in or out conditionally
GET /v1/installations/{id}/identity-policyRead the installation binding and server login policy
POST /v1/notification-receiptsReport a single-delivery iOS extension receipt
POST /v1/installations/{id}:sync-activity-distributionSynchronize optional foreground activity bins
POST /v1/installations/{id}:record-notification-eventRecord an opt-in SDK notification observation
POST /v1/installations/{id}:sync-audienceSynchronize SDK session observations
POST /v1/installations/{id}:set-client-tagsReplace the current device SDK tags
POST /v1/installationsEnroll or refresh an installation
POST /v1/installations/{id}:identifyBind an installation to a user
POST /v1/installations/{id}:logoutRemove an authenticated user binding
POST /v1/installations/{id}:transferTransfer an installation binding
GET /v1/app-users/{id}Read an app user
GET /v1/app-users/by-external-id/{external_id}Find an app user by external ID
POST /v1/push-subscriptionsRegister a push address
POST /v1/push-subscriptions:unregisterUnregister an exact push address
POST /v1/push-subscriptions/{id}/addressesAdd a new address generation
POST /v1/push-subscriptions/{id}:invalidateInvalidate a push subscription
POST /v1/push-subscriptions/{id}/addresses/{generation}:invalidateInvalidate an exact address generation
POST /v1/installations/{id}/permission-observationsReport notification permission
POST /v1/installations/{id}:set-push-preferenceSet the in-app push preference
POST /v1/app-users/{id}/marketing-consentsRecord marketing consent
GET /v1/app-users/{id}/marketing-consentsRead marketing consent
GET /v1/app-users/{id}/delivery-eligibilityRead delivery eligibility
POST /v1/messagesSubmit a message
POST /v1/broadcastsSubmit a broadcast
GET /v1/messages/{id}Read a message
GET /v1/messages/{id}/deliveriesList deliveries for a message
GET /v1/deliveriesList deliveries
POST /v1/messages/{id}:stopStop pending deliveries
POST /v1/messages/{id}/deliveries/{subscription_id}:resolve-unknownResolve an unknown delivery outcome
GET /v1/app-environments/{id}/dispatch-controlRead dispatch control
GET /v1/app-environments/{id}/address-breakerRead address circuit-breaker state
POST /v1/app-environments/{id}:reset-address-breakerReset the address circuit breaker
POST /v1/app-environments/{id}:pause-dispatchPause dispatch
POST /v1/app-environments/{id}:resume-dispatchResume dispatch
POST /v1/push-provider-connectionsCreate a provider connection
GET /v1/push-provider-connectionsList provider connections
POST /v1/push-provider-connections/{id}:rotate-credentialRotate a provider credential
POST /v1/push-provider-connections/{id}:recover-credentialRecover a provider credential
POST /v1/push-provider-connections/{id}:verifyVerify a provider connection
PUT /v1/attribute-definitions/{key}Define an attribute
GET /v1/attribute-definitionsList attribute definitions
POST /v1/app-users/{id}:set-attributesSet user attributes
PUT /v1/event-definitions/{name}Define an event
GET /v1/event-definitionsList event definitions
POST /v1/app-eventsRecord app events
GET /v1/registry/enumsRead enum definitions
GET /v1/registry/error-codesRead error definitions
GET /v1/registry/message-fieldsRead message-field definitions

POST /v1/project-messages

Submit a message to selected apps with a unified server key

Authentication: projectApiKey: messages:send

Canonical description (Korean)

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

Path, query and header inputs

Name / locationRequiredShape and bounds
Kits-Idempotency-Key · headerRequired
{
  "type": "string",
  "minLength": 1,
  "maxLength": 255,
  "pattern": "^[\\x20-\\x7E]+$"
}

Request body

Body required

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
                  }
                }
              }
            }
          ]
        }
      }
    }
  ]
}

Shared schemas: MessageRequest

Responses

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이 없거나 유효하지 않다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

GET /v1/project-messages/{id}

Read a unified message acceptance receipt (24 hours)

Authentication: projectApiKey: messages:read

Canonical description (Korean)

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

Path, query and header inputs

Name / locationRequiredShape and bounds
id · pathRequired
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

Request body

Responses

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이 없거나 유효하지 않다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

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

Read Android notification channel settings

Authentication: deviceToken: own installation only

Canonical description (Korean)

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

Path, query and header inputs

Name / locationRequiredShape and bounds
installation_id · pathRequired
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

Request body

Responses

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이 없거나 유효하지 않다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

POST /v1/identity-tokens

Issue a legacy kitid1 native login proof

Authentication: apiKey: identity:write

Canonical description (Korean)

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

Path, query and header inputs

No additional parameters are declared for this operation.

Request body

Body required

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
    }
  }
}

Responses

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이 없거나 유효하지 않다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

GET /v1/installations/{id}/identity

Read the current installation identity binding

Authentication: deviceToken: own installation only

Canonical description (Korean)

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

Path, query and header inputs

Name / locationRequiredShape and bounds
id · pathRequired
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

Request body

Responses

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이 없거나 유효하지 않다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

POST /v1/installations/{id}/identity

Log an installation in or out conditionally

Authentication: deviceToken: own installation only

Canonical description (Korean)

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

Path, query and header inputs

Name / locationRequiredShape and bounds
id · pathRequired
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

Request body

Body required

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"
              ]
            }
          ]
        }
      }
    }
  ]
}

Responses

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이 없거나 유효하지 않다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

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

Read the installation binding and server login policy

Authentication: deviceToken: own installation only

Canonical description (Korean)

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

Path, query and header inputs

Name / locationRequiredShape and bounds
id · pathRequired
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

Request body

Responses

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이 없거나 유효하지 않다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

POST /v1/notification-receipts

Report a single-delivery iOS extension receipt

Authentication: notificationReceipt: RECEIVED for one issued delivery only

Canonical description (Korean)

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

Path, query and header inputs

No additional parameters are declared for this operation.

Request body

Body required

application/json

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

Responses

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이 없거나 유효하지 않다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

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

Synchronize optional foreground activity bins

Authentication: deviceToken: own installation only

Canonical description (Korean)

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

Path, query and header inputs

Name / locationRequiredShape and bounds
id · pathRequired
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

Request body

Body required

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
            }
          }
        }
      }
    }
  }
}

Responses

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이 없거나 유효하지 않다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

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

Record an opt-in SDK notification observation

Authentication: deviceToken: own installation only

Canonical description (Korean)

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

Path, query and header inputs

Name / locationRequiredShape and bounds
id · pathRequired
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

Request body

Body required

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."
    }
  }
}

Responses

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이 없거나 유효하지 않다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

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

Synchronize SDK session observations

Authentication: deviceToken: own installation only

Canonical description (Korean)

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

Path, query and header inputs

Name / locationRequiredShape and bounds
id · pathRequired
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

Request body

Body required

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
        }
      }
    }
  }
}

Responses

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이 없거나 유효하지 않다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

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

Replace the current device SDK tags

Authentication: deviceToken: own installation only

Canonical description (Korean)

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

Path, query and header inputs

Name / locationRequiredShape and bounds
id · pathRequired
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

Request body

Body required

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
      }
    }
  }
}

Responses

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이 없거나 유효하지 않다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

POST /v1/installations

Enroll or refresh an installation

Authentication: apiKey: identity:write OR apiKey: installations:enroll

Canonical description (Korean)

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

Path, query and header inputs

No additional parameters are declared for this operation.

Request body

Body required

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"
      ]
    }
  ]
}

Responses

HTTP 401

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

Response headers

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

application/json

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

Shared schemas: 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

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

POST /v1/installations/{id}:identify

Bind an installation to a user

Authentication: apiKey: identity:write

Canonical description (Korean)

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

Path, query and header inputs

Name / locationRequiredShape and bounds
id · pathRequired
{
  "type": "string",
  "pattern": "^[^/:]+$"
}
Kits-Idempotency-Key · headerRequired
{
  "type": "string",
  "minLength": 1,
  "maxLength": 255,
  "pattern": "^[\\x20-\\x7E]+$"
}

Request body

Body required

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
    }
  }
}

Responses

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이 없거나 유효하지 않다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

POST /v1/installations/{id}:logout

Remove an authenticated user binding

Authentication: apiKey: identity:write

Canonical description (Korean)

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

Path, query and header inputs

Name / locationRequiredShape and bounds
id · pathRequired
{
  "type": "string",
  "pattern": "^[^/:]+$"
}
Kits-Idempotency-Key · headerRequired
{
  "type": "string",
  "minLength": 1,
  "maxLength": 255,
  "pattern": "^[\\x20-\\x7E]+$"
}

Request body

Body required

application/json

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

Responses

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이 없거나 유효하지 않다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

POST /v1/installations/{id}:transfer

Transfer an installation binding

Authentication: apiKey: identity:write

Canonical description (Korean)

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

Path, query and header inputs

Name / locationRequiredShape and bounds
id · pathRequired
{
  "type": "string",
  "pattern": "^[^/:]+$"
}
Kits-Idempotency-Key · headerRequired
{
  "type": "string",
  "minLength": 1,
  "maxLength": 255,
  "pattern": "^[\\x20-\\x7E]+$"
}

Request body

Body required

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
    }
  }
}

Responses

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이 없거나 유효하지 않다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

GET /v1/app-users/{id}

Read an app user

Authentication: apiKey: identity:read

Canonical description (Korean)

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

Path, query and header inputs

Name / locationRequiredShape and bounds
id · pathRequired
{
  "type": "string",
  "pattern": "^[^/:]+$"
}
subscription_limit · queryOptional
{
  "type": "integer",
  "minimum": 1,
  "maximum": 200,
  "default": 50
}
subscription_cursor · queryOptional
{
  "type": "string",
  "maxLength": 384,
  "pattern": "^[A-Za-z0-9_-]+$"
}

Request body

Responses

HTTP 401

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

Response headers

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

application/json

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

Shared schemas: Error

HTTP 2XX

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

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

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

Find an app user by external ID

Authentication: apiKey: identity:read

Canonical description (Korean)

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

Path, query and header inputs

Name / locationRequiredShape and bounds
external_id · pathRequired
{
  "type": "string",
  "pattern": "^[^/:]+$"
}
subscription_limit · queryOptional
{
  "type": "integer",
  "minimum": 1,
  "maximum": 200,
  "default": 50
}
subscription_cursor · queryOptional
{
  "type": "string",
  "maxLength": 384,
  "pattern": "^[A-Za-z0-9_-]+$"
}

Request body

Responses

HTTP 401

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

Response headers

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

application/json

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

Shared schemas: Error

HTTP 2XX

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

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

POST /v1/push-subscriptions

Register a push address

Authentication: apiKey: identity:write OR deviceToken: own installation only

Canonical description (Korean)

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

Path, query and header inputs

No additional parameters are declared for this operation.

Request body

Body required

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"
          ]
        }
      }
    }
  ]
}

Responses

HTTP 401

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

Response headers

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

application/json

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

Shared schemas: 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

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

POST /v1/push-subscriptions:unregister

Unregister an exact push address

Authentication: apiKey: identity:write OR deviceToken: own installation only

Canonical description (Korean)

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

Path, query and header inputs

No additional parameters are declared for this operation.

Request body

Body required

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"
            }
          }
        }
      }
    }
  ]
}

Responses

HTTP 200

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

application/json

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

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

Response headers

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

application/json

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

Shared schemas: Error

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

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

Add a new address generation

Authentication: apiKey: identity:write

Canonical description (Korean)

주소 세대를 회전한다

Path, query and header inputs

Name / locationRequiredShape and bounds
id · pathRequired
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

Request body

Body required

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"
          ]
        }
      }
    }
  ]
}

Responses

HTTP 401

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

Response headers

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

application/json

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

Shared schemas: 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

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

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

Invalidate a push subscription

Authentication: apiKey: identity:write

Canonical description (Korean)

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

Path, query and header inputs

Name / locationRequiredShape and bounds
id · pathRequired
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

Request body

Responses

HTTP 401

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

Response headers

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

application/json

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

Shared schemas: Error

HTTP 2XX

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

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

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

Invalidate an exact address generation

Authentication: apiKey: identity:write

Canonical description (Korean)

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

Path, query and header inputs

Name / locationRequiredShape and bounds
id · pathRequired
{
  "type": "string",
  "pattern": "^[^/:]+$"
}
generation · pathRequired
{
  "type": "integer",
  "minimum": 1,
  "maximum": 9007199254740991
}

Request body

Responses

HTTP 401

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

Response headers

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

application/json

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

Shared schemas: Error

HTTP 2XX

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

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

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

Report notification permission

Authentication: apiKey: consent:write OR deviceToken: own installation only

Canonical description (Korean)

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

Path, query and header inputs

Name / locationRequiredShape and bounds
id · pathRequired
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

Request body

Responses

HTTP 401

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

Response headers

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

application/json

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

Shared schemas: Error

HTTP 2XX

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

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

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

Set the in-app push preference

Authentication: apiKey: consent:write OR deviceToken: own installation only

Canonical description (Korean)

앱 안 알림 설정을 바꾼다

Path, query and header inputs

Name / locationRequiredShape and bounds
id · pathRequired
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

Request body

Responses

HTTP 401

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

Response headers

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

application/json

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

Shared schemas: Error

HTTP 2XX

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

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

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

Record marketing consent

Authentication: apiKey: consent:write

Canonical description (Korean)

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

Path, query and header inputs

Name / locationRequiredShape and bounds
id · pathRequired
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

Request body

Responses

HTTP 401

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

Response headers

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

application/json

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

Shared schemas: Error

HTTP 2XX

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

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

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

Read marketing consent

Authentication: apiKey: consent:read

Canonical description (Korean)

마케팅 동의 이력의 bounded keyset page

Path, query and header inputs

Name / locationRequiredShape and bounds
id · pathRequired
{
  "type": "string",
  "pattern": "^[^/:]+$"
}
limit · queryOptional
{
  "type": "integer",
  "minimum": 1,
  "maximum": 200,
  "default": 50
}
cursor · queryOptional
{
  "type": "string",
  "maxLength": 256,
  "pattern": "^[A-Za-z0-9_-]+$"
}

Request body

Responses

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이 없거나 유효하지 않다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

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

Read delivery eligibility

Authentication: apiKey: messages:read

Canonical description (Korean)

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

Path, query and header inputs

Name / locationRequiredShape and bounds
id · pathRequired
{
  "type": "string",
  "pattern": "^[^/:]+$"
}
classification · queryOptional
{
  "type": "string",
  "enum": [
    "SERVICE",
    "PROMOTIONAL"
  ],
  "default": "SERVICE"
}
subscription_state · queryOptional
{
  "type": "string",
  "enum": [
    "ALL",
    "ACTIVE",
    "INACTIVE"
  ],
  "default": "ALL"
}
limit · queryOptional
{
  "type": "integer",
  "minimum": 1,
  "maximum": 200
}
cursor · queryOptional
{
  "type": "string",
  "maxLength": 512,
  "pattern": "^[A-Za-z0-9_-]+$"
}

Request body

Responses

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이 없거나 유효하지 않다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

POST /v1/messages

Submit a message

Authentication: apiKey: messages:send

Canonical description (Korean)

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

Path, query and header inputs

Name / locationRequiredShape and bounds
Kits-Idempotency-Key · headerRequired
{
  "type": "string",
  "minLength": 1,
  "maxLength": 255,
  "pattern": "^[\\x20-\\x7E]+$"
}

Request body

Body required

application/json

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

Shared schemas: MessageRequest

Responses

HTTP 401

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

Response headers

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

application/json

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

Shared schemas: Error

HTTP 2XX

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

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

POST /v1/broadcasts

Submit a broadcast

Authentication: apiKey: broadcasts:send

Canonical description (Korean)

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

Path, query and header inputs

Name / locationRequiredShape and bounds
Kits-Idempotency-Key · headerRequired
{
  "type": "string",
  "minLength": 1,
  "maxLength": 255,
  "pattern": "^[\\x20-\\x7E]+$"
}

Request body

Responses

HTTP 401

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

Response headers

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

application/json

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

Shared schemas: Error

HTTP 2XX

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

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

GET /v1/messages/{id}

Read a message

Authentication: apiKey: messages:read

Canonical description (Korean)

요청 단위 결과 요약

Path, query and header inputs

Name / locationRequiredShape and bounds
id · pathRequired
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

Request body

Responses

HTTP 401

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

Response headers

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

application/json

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

Shared schemas: Error

HTTP 2XX

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

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

GET /v1/messages/{id}/deliveries

List deliveries for a message

Authentication: apiKey: messages:read

Canonical description (Korean)

대상별 결과

Path, query and header inputs

Name / locationRequiredShape and bounds
id · pathRequired
{
  "type": "string",
  "pattern": "^[^/:]+$"
}
limit · queryOptional
{
  "type": "integer",
  "minimum": 1,
  "maximum": 200
}
cursor · queryOptional
{
  "type": "string",
  "maxLength": 1024,
  "pattern": "^[A-Za-z0-9_-]+$"
}

Request body

Responses

HTTP 401

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

Response headers

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

application/json

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

Shared schemas: Error

HTTP 2XX

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

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

GET /v1/deliveries

List deliveries

Authentication: apiKey: dispatch-control:read

Canonical description (Korean)

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

Path, query and header inputs

Name / locationRequiredShape and bounds
state · queryRequired
{
  "type": "string",
  "enum": [
    "OUTCOME_UNKNOWN"
  ]
}
limit · queryOptional
{
  "type": "integer",
  "minimum": 1,
  "maximum": 200,
  "default": 50
}
cursor · queryOptional
{
  "type": "string",
  "maxLength": 256,
  "pattern": "^[A-Za-z0-9_-]+$"
}

Request body

Responses

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이 없거나 유효하지 않다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

POST /v1/messages/{id}:stop

Stop pending deliveries

Authentication: apiKey: dispatch-control:write

Canonical description (Korean)

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

Path, query and header inputs

Name / locationRequiredShape and bounds
id · pathRequired
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

Request body

Responses

HTTP 401

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

Response headers

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

application/json

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

Shared schemas: Error

HTTP 2XX

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

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

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

Resolve an unknown delivery outcome

Authentication: apiKey: dispatch-control:write

Canonical description (Korean)

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

Path, query and header inputs

Name / locationRequiredShape and bounds
id · pathRequired
{
  "type": "string",
  "pattern": "^[^/:]+$"
}
subscription_id · pathRequired
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

Request body

Responses

HTTP 401

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

Response headers

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

application/json

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

Shared schemas: Error

HTTP 2XX

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

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

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

Read dispatch control

Authentication: apiKey: dispatch-control:read

Canonical description (Korean)

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

Path, query and header inputs

Name / locationRequiredShape and bounds
id · pathRequired
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

Request body

Responses

HTTP 401

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

Response headers

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

application/json

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

Shared schemas: Error

HTTP 2XX

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

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

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

Read address circuit-breaker state

Authentication: apiKey: dispatch-control:read

Canonical description (Korean)

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

Path, query and header inputs

Name / locationRequiredShape and bounds
id · pathRequired
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

Request body

Responses

HTTP 401

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

Response headers

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

application/json

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

Shared schemas: Error

HTTP 2XX

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

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

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

Reset the address circuit breaker

Authentication: apiKey: dispatch-control:write

Canonical description (Korean)

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

Path, query and header inputs

Name / locationRequiredShape and bounds
id · pathRequired
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

Request body

Responses

HTTP 401

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

Response headers

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

application/json

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

Shared schemas: Error

HTTP 2XX

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

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

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

Pause dispatch

Authentication: apiKey: dispatch-control:write

Canonical description (Korean)

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

Path, query and header inputs

Name / locationRequiredShape and bounds
id · pathRequired
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

Request body

Responses

HTTP 401

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

Response headers

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

application/json

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

Shared schemas: Error

HTTP 2XX

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

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

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

Resume dispatch

Authentication: apiKey: dispatch-control:write

Canonical description (Korean)

발송 재개

Path, query and header inputs

Name / locationRequiredShape and bounds
id · pathRequired
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

Request body

Responses

HTTP 401

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

Response headers

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

application/json

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

Shared schemas: Error

HTTP 2XX

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

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

POST /v1/push-provider-connections

Create a provider connection

Authentication: apiKey: provider-connections:write

Canonical description (Korean)

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

Path, query and header inputs

No additional parameters are declared for this operation.

Request body

Responses

HTTP 401

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

Response headers

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

application/json

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

Shared schemas: Error

HTTP 2XX

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

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

GET /v1/push-provider-connections

List provider connections

Authentication: apiKey: provider-connections:read

Canonical description (Korean)

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

Path, query and header inputs

No additional parameters are declared for this operation.

Request body

Responses

HTTP 401

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

Response headers

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

application/json

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

Shared schemas: Error

HTTP 2XX

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

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

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

Rotate a provider credential

Authentication: apiKey: credentials:rotate

Canonical description (Korean)

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

Path, query and header inputs

Name / locationRequiredShape and bounds
id · pathRequired
{
  "type": "string",
  "pattern": "^[^/:]+$"
}
Kits-Idempotency-Key · headerRequired
{
  "type": "string",
  "minLength": 1,
  "maxLength": 255,
  "pattern": "^[\\x20-\\x7E]+$"
}

Request body

Responses

HTTP 401

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

Response headers

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

application/json

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

Shared schemas: Error

HTTP 2XX

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

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

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

Recover a provider credential

Authentication: apiKey: credentials:rotate

Canonical description (Korean)

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

Path, query and header inputs

Name / locationRequiredShape and bounds
id · pathRequired
{
  "type": "string",
  "pattern": "^[^/:]+$"
}
Kits-Idempotency-Key · headerRequired
{
  "type": "string",
  "minLength": 1,
  "maxLength": 255,
  "pattern": "^[\\x20-\\x7E]+$"
}

Request body

Responses

HTTP 401

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

Response headers

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

application/json

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

Shared schemas: Error

HTTP 2XX

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

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

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

Verify a provider connection

Authentication: apiKey: provider-connections:write

Canonical description (Korean)

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

Path, query and header inputs

Name / locationRequiredShape and bounds
id · pathRequired
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

Request body

Responses

HTTP 401

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

Response headers

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

application/json

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

Shared schemas: Error

HTTP 2XX

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

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

PUT /v1/attribute-definitions/{key}

Define an attribute

Authentication: apiKey: attributes:write

Canonical description (Korean)

속성 키와 타입을 등록한다

Path, query and header inputs

Name / locationRequiredShape and bounds
key · pathRequired
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

Request body

Responses

HTTP 401

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

Response headers

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

application/json

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

Shared schemas: Error

HTTP 2XX

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

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

GET /v1/attribute-definitions

List attribute definitions

Authentication: apiKey: attributes:read

Canonical description (Korean)

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

Path, query and header inputs

Name / locationRequiredShape and bounds
limit · queryOptional
{
  "type": "integer",
  "minimum": 1,
  "maximum": 200,
  "default": 50
}
cursor · queryOptional
{
  "type": "string",
  "maxLength": 256,
  "pattern": "^[A-Za-z0-9_-]+$"
}

Request body

Responses

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이 없거나 유효하지 않다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

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

Set user attributes

Authentication: apiKey: attributes:write

Canonical description (Korean)

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

Path, query and header inputs

Name / locationRequiredShape and bounds
id · pathRequired
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

Request body

Responses

HTTP 401

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

Response headers

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

application/json

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

Shared schemas: Error

HTTP 2XX

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

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

PUT /v1/event-definitions/{name}

Define an event

Authentication: apiKey: events:write

Canonical description (Korean)

이벤트 이름을 등록한다

Path, query and header inputs

Name / locationRequiredShape and bounds
name · pathRequired
{
  "type": "string",
  "pattern": "^[^/:]+$"
}

Request body

Responses

HTTP 401

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

Response headers

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

application/json

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

Shared schemas: Error

HTTP 2XX

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

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

GET /v1/event-definitions

List event definitions

Authentication: apiKey: events:read

Canonical description (Korean)

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

Path, query and header inputs

Name / locationRequiredShape and bounds
limit · queryOptional
{
  "type": "integer",
  "minimum": 1,
  "maximum": 200,
  "default": 50
}
cursor · queryOptional
{
  "type": "string",
  "maxLength": 256,
  "pattern": "^[A-Za-z0-9_-]+$"
}

Request body

Responses

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이 없거나 유효하지 않다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

POST /v1/app-events

Record app events

Authentication: apiKey: events:write

Canonical description (Korean)

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

Path, query and header inputs

No additional parameters are declared for this operation.

Request body

Responses

HTTP 401

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

Response headers

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

application/json

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

Shared schemas: Error

HTTP 2XX

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

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

GET /v1/registry/enums

Read enum definitions

Authentication: apiKey: authentication required; no additional scope

Canonical description (Korean)

상태값 레지스트리 전체

Path, query and header inputs

No additional parameters are declared for this operation.

Request body

Responses

HTTP 401

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

Response headers

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

application/json

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

Shared schemas: Error

HTTP 2XX

성공

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

GET /v1/registry/error-codes

Read error definitions

Authentication: apiKey: authentication required; no additional scope

Canonical description (Korean)

오류 코드 레지스트리 전체

Path, query and header inputs

No additional parameters are declared for this operation.

Request body

Responses

HTTP 401

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

Response headers

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

application/json

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

Shared schemas: Error

HTTP 2XX

성공

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

GET /v1/registry/message-fields

Read message-field definitions

Authentication: apiKey: authentication required; no additional scope

Canonical description (Korean)

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

Path, query and header inputs

No additional parameters are declared for this operation.

Request body

Responses

HTTP 401

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

Response headers

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

application/json

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

Shared schemas: Error

HTTP 2XX

성공

HTTP 4XX

요청이 거절됐다

Response headers

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

application/json

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

Shared schemas: Error

HTTP 5XX

우리 쪽 오류

Response headers

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

application/json

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

Shared schemas: Error

Shared JSON Schema

Shared definitions referenced by $ref. Description strings retain the source language; fields, required values and constraints form the machine-readable contract.

Error

Expand schema
{
  "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"
        }
      }
    }
  }
}

Shared schemas: FieldError

FieldError

Expand schema
{
  "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

Expand schema
{
  "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"
        ]
      }
    }
  ]
}

Shared schemas: AndroidVisibility · IosInterruptionLevel · MessageClassification · MessagePriority

SubscriptionKind

Expand schema
{
  "type": "string",
  "enum": [
    "IOS_PUSH",
    "ANDROID_PUSH"
  ],
  "description": "REQ-ID-009"
}

SubscriptionState

Expand schema
{
  "type": "string",
  "enum": [
    "ACTIVE",
    "INVALIDATED"
  ],
  "description": "REQ-ID-005, REQ-DLV-006"
}

AddressState

Expand schema
{
  "type": "string",
  "enum": [
    "ACTIVE",
    "SUPERSEDED",
    "INVALIDATED",
    "RETIRED"
  ],
  "description": "REQ-ID-012"
}

AddressType

Expand schema
{
  "type": "string",
  "enum": [
    "FCM_FID",
    "FCM_REGISTRATION_TOKEN_LEGACY",
    "APNS_DEVICE_TOKEN"
  ],
  "description": "REQ-ID-012"
}

CredentialVerificationState

Expand schema
{
  "type": "string",
  "enum": [
    "PENDING",
    "PROPAGATING",
    "VERIFIED",
    "DEGRADED",
    "FAILED"
  ],
  "description": "REQ-PRV-003"
}

CredentialVerificationReason

Expand schema
{
  "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

Expand schema
{
  "type": "string",
  "enum": [
    "ELIGIBLE",
    "NOT_FOUND",
    "NOT_AUTHORIZED",
    "SUPPRESSED"
  ],
  "description": "REQ-CS-005"
}

IdentityVerificationState

Expand schema
{
  "type": "string",
  "enum": [
    "UNVERIFIED",
    "VERIFIED",
    "EXPIRED"
  ],
  "description": "REQ-ID-008"
}

OsPermissionState

Expand schema
{
  "type": "string",
  "enum": [
    "NOT_DETERMINED",
    "AUTHORIZED",
    "DENIED",
    "PROVISIONAL",
    "EPHEMERAL"
  ],
  "description": "REQ-CS-001"
}

PushPreference

Expand schema
{
  "type": "string",
  "enum": [
    "OPTED_IN",
    "OPTED_OUT"
  ],
  "description": "REQ-CS-002"
}

MarketingConsentState

Expand schema
{
  "type": "string",
  "enum": [
    "GRANTED",
    "WITHDRAWN",
    "UNKNOWN"
  ],
  "description": "REQ-CS-003"
}

MessageClassification

Expand schema
{
  "type": "string",
  "enum": [
    "SERVICE",
    "PROMOTIONAL"
  ],
  "description": "REQ-CS-004"
}

MessagePriority

Expand schema
{
  "type": "string",
  "enum": [
    "NORMAL",
    "HIGH"
  ],
  "description": "REQ-MSG-006"
}

DisplayPath

Expand schema
{
  "type": "string",
  "enum": [
    "OS_DISPLAY",
    "APP_DISPLAY"
  ],
  "description": "REQ-MSG-006"
}

MessageOrigin

Expand schema
{
  "type": "string",
  "enum": [
    "TRANSACTIONAL_API",
    "DASHBOARD_BROADCAST"
  ],
  "description": "REQ-MSG-001"
}

DeliveryState

Expand schema
{
  "type": "string",
  "enum": [
    "PENDING",
    "READY",
    "LEASED",
    "IN_FLIGHT",
    "RETRY_SCHEDULED",
    "ACCEPTED",
    "REJECTED_PERMANENT",
    "OUTCOME_UNKNOWN",
    "SUPPRESSED"
  ],
  "description": "REQ-MSG-012"
}

SuppressionReason

Expand schema
{
  "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

Expand schema
{
  "type": "string",
  "enum": [
    "ADDRESS_PERMANENTLY_INVALID",
    "CREDENTIAL_PROBLEM",
    "REQUEST_ERROR",
    "TRANSIENT",
    "OUTCOME_UNKNOWN",
    "PRECONDITION_STALE",
    "RETRY_BUDGET_EXHAUSTED"
  ],
  "description": "REQ-DLV-005"
}

IosInterruptionLevel

Expand schema
{
  "type": "string",
  "enum": [
    "passive",
    "active",
    "time-sensitive",
    "critical"
  ],
  "description": "REQ-MSG-005"
}

AndroidVisibility

Expand schema
{
  "type": "string",
  "enum": [
    "PUBLIC",
    "PRIVATE",
    "SECRET"
  ],
  "description": "REQ-MSG-005"
}

MetricAvailability

Expand schema
{
  "type": "string",
  "enum": [
    "MEASURED",
    "NOT_MEASURABLE"
  ],
  "description": "REQ-DLV-002"
}

AddressInvalidationReason

Expand schema
{
  "type": "string",
  "enum": [
    "ADDRESS_PERMANENTLY_INVALID",
    "OPERATOR_REVOKED"
  ],
  "description": "REQ-DLV-005"
}

IdempotencyOperation

Expand schema
{
  "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"
}