API 참조
API 버전 2026-11-09 · OpenAPI 3.1 YAML 다운로드
인증은 워크스페이스 범위의 product key를 사용해요: Authorization: Bearer pk_v1_…. 키에는 명시적 스코프와 선택적 계정 허용 목록이 있고, 다른 키를 만들거나 결제를 변경할 수는 없어요.
모든 변경 작업에는 Idempotency-Key 헤더가 필요하고, 편집과 예약에는 expectedVersion도 필요해요. Publish와 schedule은 수신처별 전송 ID 하나와 함께 202 Accepted를 반환해요: 202는 무언가가 게시됐다는 주장이 절대 아니에요. 결과는 GET /posts/{id}, 고객 웹훅, 또는 백오프가 있는 제한된 폴링으로 확인하세요.
오류는 contract v1의 정규화된 봉투를 사용해요: code, 안전한 message, fieldErrors, destinationErrors, retryable, retryAfterSeconds, requestId. 게시 크레딧이나 할당량 오류 코드는 의도적으로 없어요.
인증
워크스페이스 제품 키를 "Authorization: Bearer pk_v1_…"로 보내세요. 각 작업에 필요한 범위가 표시됩니다. 인증 및 권한을 보세요.
GET /capabilities
허용된 수신처의 적격 형식과 옵션
accounts:read 스코프가 필요해요.
작업 세부 사항에는 매개변수, 요청 본문, 응답 및 구성요소 참조가 포함됩니다. 참조 정의는 아래에 표시됩니다.
{
"tags": [
"accounts"
],
"summary": "허용된 수신처의 적격 형식과 옵션",
"description": "`accounts:read` 스코프가 필요해요.",
"responses": {
"200": {
"description": "Capability list",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"capabilities",
"requestId"
],
"properties": {
"capabilities": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Capability"
}
},
"requestId": {
"type": "string"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}GET /accounts
이 키에 보이는 수신처 계정 목록
키의 계정 허용 목록을 존중해요. accounts:read 스코프가 필요해요.
작업 세부 사항에는 매개변수, 요청 본문, 응답 및 구성요소 참조가 포함됩니다. 참조 정의는 아래에 표시됩니다.
{
"tags": [
"accounts"
],
"summary": "이 키에 보이는 수신처 계정 목록",
"description": "키의 계정 허용 목록을 존중해요. `accounts:read` 스코프가 필요해요.",
"parameters": [
{
"$ref": "#/components/parameters/cursor"
},
{
"$ref": "#/components/parameters/limit"
}
],
"responses": {
"200": {
"description": "Account page",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"accounts",
"requestId"
],
"properties": {
"accounts": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Account"
}
},
"nextCursor": {
"type": [
"string",
"null"
]
},
"requestId": {
"type": "string"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}GET /accounts/{id}/tiktok/settings
허용된 연결 계정의 검증된 TikTok 크리에이터 설정 조회
accounts:read와 키의 계정 허용 목록이 필요해요. 이 조회는 사람의 게시 동의를 절대 공급하지 않아요.
작업 세부 사항에는 매개변수, 요청 본문, 응답 및 구성요소 참조가 포함됩니다. 참조 정의는 아래에 표시됩니다.
{
"tags": [
"accounts"
],
"summary": "허용된 연결 계정의 검증된 TikTok 크리에이터 설정 조회",
"description": "accounts:read와 키의 계정 허용 목록이 필요해요. 이 조회는 사람의 게시 동의를 절대 공급하지 않아요.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Current typed creator settings; a person must confirm choices in the composer",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"settings",
"humanConfirmationRequired",
"requestId"
],
"properties": {
"settings": {
"$ref": "#/components/schemas/TikTokCreatorSettings"
},
"humanConfirmationRequired": {
"type": "boolean",
"const": true
},
"requestId": {
"type": "string"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}POST /media/upload-intents
바이트를 예약하고 직접 업로드 지시를 반환
media:write 스코프와 Idempotency-Key가 필요해요. 바이트는 반환된 지시를 사용해 비공개 오브젝트 스토리지로 직접 업로드돼요; 이 API를 절대 통과하지 않아요. 영구 공개 미디어 URL은 존재하지 않아요.
작업 세부 사항에는 매개변수, 요청 본문, 응답 및 구성요소 참조가 포함됩니다. 참조 정의는 아래에 표시됩니다.
{
"tags": [
"media"
],
"summary": "바이트를 예약하고 직접 업로드 지시를 반환",
"description": "`media:write` 스코프와 Idempotency-Key가 필요해요. 바이트는 반환된 지시를 사용해 비공개 오브젝트 스토리지로 직접 업로드돼요; 이 API를 절대 통과하지 않아요. 영구 공개 미디어 URL은 존재하지 않아요.\n",
"parameters": [
{
"$ref": "#/components/parameters/idempotencyKey"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UploadIntentRequest"
}
}
}
},
"responses": {
"201": {
"description": "Upload instructions created",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UploadIntentResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/PaymentRequired"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"422": {
"$ref": "#/components/responses/Validation"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}GET /media/{id}
미디어 상태와 만료(영구 공개 URL 없음)
작업 세부 사항에는 매개변수, 요청 본문, 응답 및 구성요소 참조가 포함됩니다. 참조 정의는 아래에 표시됩니다.
{
"tags": [
"media"
],
"summary": "미디어 상태와 만료(영구 공개 URL 없음)",
"parameters": [
{
"$ref": "#/components/parameters/id"
}
],
"responses": {
"200": {
"description": "Media status",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"media",
"requestId"
],
"properties": {
"media": {
"$ref": "#/components/schemas/MediaStatus"
},
"requestId": {
"type": "string"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}POST /media/{id}/upload-parts
기존 업로드 세션에서 1개 이상 64개 이하의 멀티파트 PUT URL 갱신
작업 세부 사항에는 매개변수, 요청 본문, 응답 및 구성요소 참조가 포함됩니다. 참조 정의는 아래에 표시됩니다.
{
"tags": [
"media"
],
"summary": "기존 업로드 세션에서 1개 이상 64개 이하의 멀티파트 PUT URL 갱신",
"parameters": [
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/idempotencyKey"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"fromPart",
"toPart"
],
"properties": {
"fromPart": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"toPart": {
"type": "integer",
"minimum": 1,
"maximum": 10000
}
}
}
}
}
},
"responses": {
"200": {
"description": "Fresh upload URLs; toPart must be at least fromPart and at most fromPart + 63",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"sessionId",
"parts",
"requestId"
],
"properties": {
"sessionId": {
"type": "string",
"format": "uuid"
},
"requestId": {
"type": "string"
},
"parts": {
"type": "array",
"items": {
"type": "object",
"required": [
"partNumber",
"url",
"expiresAt"
],
"properties": {
"partNumber": {
"type": "integer"
},
"url": {
"type": "string",
"format": "uri"
},
"expiresAt": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"422": {
"$ref": "#/components/responses/Validation"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}POST /media/{id}/abandon
불완전한 업로드를 포기하고 스토리지 예약 해제
작업 세부 사항에는 매개변수, 요청 본문, 응답 및 구성요소 참조가 포함됩니다. 참조 정의는 아래에 표시됩니다.
{
"tags": [
"media"
],
"summary": "불완전한 업로드를 포기하고 스토리지 예약 해제",
"parameters": [
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/idempotencyKey"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Abandoned; failed external cleanup remains durably queued",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"abandoned",
"requestId"
],
"properties": {
"abandoned": {
"type": "boolean",
"const": true
},
"requestId": {
"type": "string"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}POST /media/{id}/finalize
업로드된 오브젝트를 검증하고 사용 가능하게 만들기
media:write 스코프와 Idempotency-Key가 필요해요. 서버는 불변인 최종(FINAL) 사본에 대해 크기/MIME과 제한된 서명을 검증해요; 바이트 예약은 정확히 한 번 정산돼요. 세션 식별자만 보내세요(해당 시 멀티파트 파트 영수증도): 모든 메타데이터는 서버가 직접 관찰해요.
작업 세부 사항에는 매개변수, 요청 본문, 응답 및 구성요소 참조가 포함됩니다. 참조 정의는 아래에 표시됩니다.
{
"tags": [
"media"
],
"summary": "업로드된 오브젝트를 검증하고 사용 가능하게 만들기",
"description": "`media:write` 스코프와 Idempotency-Key가 필요해요. 서버는 불변인 최종(FINAL) 사본에 대해 크기/MIME과 제한된 서명을 검증해요; 바이트 예약은 정확히 한 번 정산돼요. 세션 식별자만 보내세요(해당 시 멀티파트 파트 영수증도): 모든 메타데이터는 서버가 직접 관찰해요.\n",
"parameters": [
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/idempotencyKey"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FinalizeRequest"
}
}
}
},
"responses": {
"200": {
"description": "Finalized",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"media",
"requestId"
],
"properties": {
"media": {
"$ref": "#/components/schemas/FinalizeResult"
},
"requestId": {
"type": "string"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"422": {
"$ref": "#/components/responses/Validation"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}POST /posts
초안 만들기
posts:write 스코프와 Idempotency-Key가 필요해요. 본문은 contract v1의 엄격한 DraftInputSchema로 파싱돼요; 중복 수신처 계정은 거부돼요. 저장은 관대해요: 게시 전에 검증하세요.
작업 세부 사항에는 매개변수, 요청 본문, 응답 및 구성요소 참조가 포함됩니다. 참조 정의는 아래에 표시됩니다.
{
"tags": [
"posts"
],
"summary": "초안 만들기",
"description": "`posts:write` 스코프와 Idempotency-Key가 필요해요. 본문은 contract v1의 엄격한 DraftInputSchema로 파싱돼요; 중복 수신처 계정은 거부돼요. 저장은 관대해요: 게시 전에 검증하세요.\n",
"parameters": [
{
"$ref": "#/components/parameters/idempotencyKey"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DraftInput"
}
}
}
},
"responses": {
"201": {
"description": "Draft created",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"post",
"requestId"
],
"properties": {
"post": {
"$ref": "#/components/schemas/DraftSaveResult"
},
"requestId": {
"type": "string"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"422": {
"$ref": "#/components/responses/Validation"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}GET /posts
게시물 목록
작업 세부 사항에는 매개변수, 요청 본문, 응답 및 구성요소 참조가 포함됩니다. 참조 정의는 아래에 표시됩니다.
{
"tags": [
"posts"
],
"summary": "게시물 목록",
"parameters": [
{
"$ref": "#/components/parameters/cursor"
},
{
"$ref": "#/components/parameters/limit"
},
{
"name": "state",
"in": "query",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Post page",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"posts",
"requestId"
],
"properties": {
"posts": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PostListItem"
}
},
"nextCursor": {
"type": [
"string",
"null"
]
},
"requestId": {
"type": "string"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}GET /posts/{id}
게시물 집계 및 수신처별 상태
"제공자가 수락함"은 "게시됨"이 아니에요. 네이티브 링크는 확인된 영수증 이후에만 나타나요; 퍼머링크가 없다는 것이 실패의 증거는 아니에요.
작업 세부 사항에는 매개변수, 요청 본문, 응답 및 구성요소 참조가 포함됩니다. 참조 정의는 아래에 표시됩니다.
{
"tags": [
"posts"
],
"summary": "게시물 집계 및 수신처별 상태",
"description": "\"제공자가 수락함\"은 \"게시됨\"이 아니에요. 네이티브 링크는 확인된 영수증 이후에만 나타나요; 퍼머링크가 없다는 것이 실패의 증거는 아니에요.\n",
"parameters": [
{
"$ref": "#/components/parameters/id"
}
],
"responses": {
"200": {
"description": "Post status",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"post",
"requestId"
],
"properties": {
"post": {
"$ref": "#/components/schemas/PostStatus"
},
"requestId": {
"type": "string"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}PATCH /posts/{id}
초안 편집(버전 검사)
Idempotency-Key와 expectedVersion이 필요해요. 오래된 버전은 현재 버전이 담긴 error.details.currentVersion과 함께 409 revision_conflict를 반환해요.
작업 세부 사항에는 매개변수, 요청 본문, 응답 및 구성요소 참조가 포함됩니다. 참조 정의는 아래에 표시됩니다.
{
"tags": [
"posts"
],
"summary": "초안 편집(버전 검사)",
"description": "Idempotency-Key와 expectedVersion이 필요해요. 오래된 버전은 현재 버전이 담긴 `error.details.currentVersion`과 함께 409 revision_conflict를 반환해요.\n",
"parameters": [
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/idempotencyKey"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DraftUpdateInput"
}
}
}
},
"responses": {
"200": {
"description": "Updated draft",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"post",
"requestId"
],
"properties": {
"post": {
"$ref": "#/components/schemas/DraftSaveResult"
},
"requestId": {
"type": "string"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"422": {
"$ref": "#/components/responses/Validation"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}POST /posts/{id}/validate
구조화된 수신처별 검증(변경 없음)
수신처에 문제가 있으면 validation.valid=false와 함께 200을 반환해요(콘텐츠 문제에 대한 오류 상태는 절대 아님).
작업 세부 사항에는 매개변수, 요청 본문, 응답 및 구성요소 참조가 포함됩니다. 참조 정의는 아래에 표시됩니다.
{
"tags": [
"posts"
],
"summary": "구조화된 수신처별 검증(변경 없음)",
"description": "수신처에 문제가 있으면 `validation.valid=false`와 함께 200을 반환해요(콘텐츠 문제에 대한 오류 상태는 절대 아님).\n",
"parameters": [
{
"$ref": "#/components/parameters/id"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"expectedVersion": {
"type": "integer",
"minimum": 1
}
}
}
}
}
},
"responses": {
"200": {
"description": "Validation result",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"validation",
"requestId"
],
"properties": {
"validation": {
"$ref": "#/components/schemas/ValidationResult"
},
"requestId": {
"type": "string"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}POST /posts/{id}/publish
지금 게시(202)
posts:publish 스코프와 Idempotency-Key가 필요해요. 선택적 expectedVersion은 편집과 같은 낙관적 동시성 보장을 적용해요. 수신처별 전송 ID 하나를 반환해요; 게시됨을 절대 주장하지 않아요.
작업 세부 사항에는 매개변수, 요청 본문, 응답 및 구성요소 참조가 포함됩니다. 참조 정의는 아래에 표시됩니다.
{
"tags": [
"posts"
],
"summary": "지금 게시(202)",
"description": "`posts:publish` 스코프와 Idempotency-Key가 필요해요. 선택적 `expectedVersion`은 편집과 같은 낙관적 동시성 보장을 적용해요. 수신처별 전송 ID 하나를 반환해요; 게시됨을 절대 주장하지 않아요.\n",
"parameters": [
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/idempotencyKey"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"expectedVersion": {
"type": "integer",
"minimum": 1
}
}
}
}
}
},
"responses": {
"202": {
"description": "Accepted for dispatch",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AcceptedOperation"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/PaymentRequired"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"422": {
"$ref": "#/components/responses/Validation"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}POST /posts/{id}/schedule
고정된 리비전 예약(202)
posts:publish 스코프와 Idempotency-Key, expectedVersion이 필요해요. 배치 전체에 시각 하나; 미래여야 하고 90일 범위 안이어야 해요(공유 서비스가 강제해요). V1에서 revisionId는 null이어야 해요: 임의 리비전 선택은 지원되지 않고 거부돼요.
작업 세부 사항에는 매개변수, 요청 본문, 응답 및 구성요소 참조가 포함됩니다. 참조 정의는 아래에 표시됩니다.
{
"tags": [
"posts"
],
"summary": "고정된 리비전 예약(202)",
"description": "`posts:publish` 스코프와 Idempotency-Key, expectedVersion이 필요해요. 배치 전체에 시각 하나; 미래여야 하고 90일 범위 안이어야 해요(공유 서비스가 강제해요). V1에서 `revisionId`는 null이어야 해요: 임의 리비전 선택은 지원되지 않고 거부돼요.\n",
"parameters": [
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/idempotencyKey"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ScheduleRequest"
}
}
}
},
"responses": {
"202": {
"description": "Scheduled",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AcceptedOperation"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/PaymentRequired"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"422": {
"$ref": "#/components/responses/Validation"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}POST /deliveries/{id}/cancel
아직 안전하게 접수되지 않았을 때 하나의 수신처 작업 취소
posts:publish 스코프와 Idempotency-Key가 필요해요. 이미 제출된 전송은 실제 상태와 함께 409 too_late_to_cancel을 반환해요.
작업 세부 사항에는 매개변수, 요청 본문, 응답 및 구성요소 참조가 포함됩니다. 참조 정의는 아래에 표시됩니다.
{
"tags": [
"deliveries"
],
"summary": "아직 안전하게 접수되지 않았을 때 하나의 수신처 작업 취소",
"description": "`posts:publish` 스코프와 Idempotency-Key가 필요해요. 이미 제출된 전송은 실제 상태와 함께 409 too_late_to_cancel을 반환해요.\n",
"parameters": [
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/idempotencyKey"
}
],
"responses": {
"200": {
"description": "Cancellation result",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"delivery",
"requestId"
],
"properties": {
"delivery": {
"type": "object",
"required": [
"deliveryId",
"canceled",
"state"
],
"properties": {
"deliveryId": {
"type": "string"
},
"canceled": {
"type": "boolean"
},
"state": {
"type": "string"
}
}
},
"requestId": {
"type": "string"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}POST /deliveries/{id}/retry
알려진 실패한 수신처 하나 재시도
posts:publish 스코프와 Idempotency-Key가 필요해요. 알 수 없는 결과나 성공한 전송은 거부돼요: 재시도하면 게시물이 중복될 수 있어요.
작업 세부 사항에는 매개변수, 요청 본문, 응답 및 구성요소 참조가 포함됩니다. 참조 정의는 아래에 표시됩니다.
{
"tags": [
"deliveries"
],
"summary": "알려진 실패한 수신처 하나 재시도",
"description": "`posts:publish` 스코프와 Idempotency-Key가 필요해요. 알 수 없는 결과나 성공한 전송은 거부돼요: 재시도하면 게시물이 중복될 수 있어요.\n",
"parameters": [
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/idempotencyKey"
}
],
"responses": {
"200": {
"description": "Retry accepted",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"delivery",
"requestId"
],
"properties": {
"delivery": {
"type": "object",
"required": [
"deliveryId",
"state"
],
"properties": {
"deliveryId": {
"type": "string"
},
"state": {
"type": "string"
}
}
},
"requestId": {
"type": "string"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}GET /usage
플랜, 계정/시트/스토리지 사용량, 활동 및 속도 정보
usage:read 스코프가 필요해요. 어떤 종류의 남은 게시 카운터도 포함하지 않아요: 모든 유료 플랜에서 게시는 무제한이에요.
작업 세부 사항에는 매개변수, 요청 본문, 응답 및 구성요소 참조가 포함됩니다. 참조 정의는 아래에 표시됩니다.
{
"tags": [
"usage"
],
"summary": "플랜, 계정/시트/스토리지 사용량, 활동 및 속도 정보",
"description": "`usage:read` 스코프가 필요해요. 어떤 종류의 남은 게시 카운터도 포함하지 않아요: 모든 유료 플랜에서 게시는 무제한이에요.\n",
"responses": {
"200": {
"description": "Usage snapshot",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"usage",
"requestId"
],
"properties": {
"usage": {
"$ref": "#/components/schemas/Usage"
},
"requestId": {
"type": "string"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}POST /webhooks
고객 이벤트 수신처 등록
webhooks:manage 스코프와 Idempotency-Key가 필요해요. HTTPS만 허용돼요; SSRF 검증(스킴, 자격 증명, 제한된 DNS 확인 주소)은 저장 전에 실행돼요. 서명 시크릿은 첫(FIRST) 생성 응답에서만 반환돼요: 멱등 재생은 시크릿 없이 엔드포인트를 반환해요. 생성은 대상 지정된 검증 이벤트도 큐에 넣어요.
작업 세부 사항에는 매개변수, 요청 본문, 응답 및 구성요소 참조가 포함됩니다. 참조 정의는 아래에 표시됩니다.
{
"tags": [
"webhooks"
],
"summary": "고객 이벤트 수신처 등록",
"description": "`webhooks:manage` 스코프와 Idempotency-Key가 필요해요. HTTPS만 허용돼요; SSRF 검증(스킴, 자격 증명, 제한된 DNS 확인 주소)은 저장 전에 실행돼요. 서명 시크릿은 첫(FIRST) 생성 응답에서만 반환돼요: 멱등 재생은 시크릿 없이 엔드포인트를 반환해요. 생성은 대상 지정된 검증 이벤트도 큐에 넣어요.\n",
"parameters": [
{
"$ref": "#/components/parameters/idempotencyKey"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateWebhookRequest"
}
}
}
},
"responses": {
"201": {
"description": "Endpoint created (secret shown once)",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"webhook",
"requestId"
],
"properties": {
"webhook": {
"allOf": [
{
"$ref": "#/components/schemas/WebhookEndpoint"
},
{
"type": "object",
"properties": {
"secret": {
"type": [
"string",
"null"
],
"description": "Present only on the first successful creation; null on replay."
}
}
}
]
},
"requestId": {
"type": "string"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"422": {
"$ref": "#/components/responses/Validation"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}GET /webhooks
이벤트 수신처 목록(시크릿 없음)
작업 세부 사항에는 매개변수, 요청 본문, 응답 및 구성요소 참조가 포함됩니다. 참조 정의는 아래에 표시됩니다.
{
"tags": [
"webhooks"
],
"summary": "이벤트 수신처 목록(시크릿 없음)",
"responses": {
"200": {
"description": "Endpoint list",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"webhooks",
"requestId"
],
"properties": {
"webhooks": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WebhookEndpoint"
}
},
"requestId": {
"type": "string"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}DELETE /webhooks/{id}
이벤트 수신처 제거
webhooks:manage 스코프와 Idempotency-Key가 필요해요(반복은 안전해요).
작업 세부 사항에는 매개변수, 요청 본문, 응답 및 구성요소 참조가 포함됩니다. 참조 정의는 아래에 표시됩니다.
{
"tags": [
"webhooks"
],
"summary": "이벤트 수신처 제거",
"description": "`webhooks:manage` 스코프와 Idempotency-Key가 필요해요(반복은 안전해요).",
"parameters": [
{
"$ref": "#/components/parameters/id"
},
{
"$ref": "#/components/parameters/idempotencyKey"
}
],
"responses": {
"204": {
"description": "Deleted",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}공통 정의
securitySchemes
productKey
{
"type": "http",
"scheme": "bearer",
"bearerFormat": "pk_v1_… (product key; NOT a Supabase key)"
}parameters
id
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}cursor
{
"name": "cursor",
"in": "query",
"schema": {
"type": "string"
}
}limit
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
}idempotencyKey
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"description": "같은 키 + 같은 정규화된 본문은 기록된 결과를 재생해요; 같은 키 + 다른 본문은 409 idempotency_conflict를 반환해요.\n"
}headers
requestId
{
"description": "요청별 상관 ID, 오류 봉투에도 그대로 포함돼요.",
"schema": {
"type": "string"
}
}retryAfter
{
"description": "다음 속도 제한 창까지의 초.",
"schema": {
"type": "integer"
}
}responses
Forbidden
{
"description": "키에 필요한 스코프가 없거나, 리소스가 다른 워크스페이스에 속해 있어요.",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}PaymentRequired
{
"description": "자격 문제(구독 비활성, 체험 만료, 계정/시트/스토리지 제한).",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}NotFound
{
"description": "리소스가 호출자의 워크스페이스에 존재하지 않아요.",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}Conflict
{
"description": "버전/멱등성/취소/동의/전송 상태 충돌.",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}Validation
{
"description": "요청 본문이나 수신처 콘텐츠가 검증에 실패했어요.",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}RateLimited
{
"description": "워크스페이스별 기술적 속도 제한이에요. 속도 제어일 뿐: 게시 할당량은 절대 아니에요.",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
},
"Retry-After": {
"$ref": "#/components/headers/retryAfter"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}ServerError
{
"description": "안전한 5XX(제공자 사용 불가 또는 예상치 못한 내부 오류). 원시 진단은 절대 포함하지 않아요.",
"headers": {
"x-request-id": {
"$ref": "#/components/headers/requestId"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}schemas
Error
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message",
"requestId"
],
"properties": {
"code": {
"type": "string",
"enum": [
"unauthenticated",
"forbidden_scope",
"account_not_allowed",
"account_limit",
"seat_limit",
"storage_limit",
"subscription_inactive",
"trial_expired",
"validation_failed",
"unsupported_format",
"consent_required",
"reconnect_required",
"destination_identity_changed",
"revision_conflict",
"idempotency_conflict",
"too_late_to_cancel",
"media_expired",
"media_deleting",
"rate_limited",
"provider_unavailable",
"submission_unknown",
"destination_conflict",
"not_found",
"internal_error"
]
},
"message": {
"type": "string"
},
"fieldErrors": {
"type": "array",
"items": {
"type": "object",
"required": [
"field",
"code",
"message"
],
"properties": {
"field": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
}
}
}
},
"destinationErrors": {
"type": "array",
"items": {
"type": "object",
"required": [
"accountId",
"code",
"message"
],
"properties": {
"accountId": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
}
}
}
},
"retryable": {
"type": "boolean"
},
"retryAfterSeconds": {
"type": "integer"
},
"details": {
"type": "object",
"additionalProperties": true,
"description": "Machine-readable extras, e.g. currentVersion for revision_conflict."
},
"requestId": {
"type": "string"
},
"requiresAction": {
"type": "object",
"description": "Session UI handoff for human consent; never contains credentials or grants access.",
"required": [
"type",
"url",
"accountIds"
],
"properties": {
"type": {
"type": "string",
"const": "human_consent"
},
"url": {
"type": "string",
"format": "uri-reference"
},
"accountIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"workspaceId": {
"type": "string",
"format": "uuid",
"description": "Verified key workspace; the browser must verify membership before switching its selected workspace."
}
}
}
}
}
}
}Account
{
"type": "object",
"required": [
"id",
"network",
"destinationType",
"displayName",
"connectionState"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"network": {
"type": "string",
"example": "instagram"
},
"destinationType": {
"type": "string",
"example": "professional_account"
},
"displayName": {
"type": "string"
},
"connectionState": {
"type": "string",
"example": "connected"
},
"capabilityVersion": {
"type": [
"string",
"null"
]
}
}
}Capability
{
"type": "object",
"required": [
"accountId",
"network"
],
"properties": {
"accountId": {
"type": "string"
},
"network": {
"type": "string"
},
"networkEnabled": {
"type": "boolean"
},
"accountConnected": {
"type": "boolean"
},
"capabilityVersion": {
"type": [
"string",
"null"
]
},
"formats": {
"type": "array",
"items": {
"type": "object",
"properties": {
"format": {
"type": "string",
"enum": [
"text",
"single_image",
"image_set",
"video"
]
},
"maxMediaCount": {
"type": "integer"
},
"maxBytes": {
"type": [
"integer",
"null"
]
},
"requiredFields": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"eligibleVisibility": {
"type": "array",
"items": {
"type": "string"
}
},
"requiresActionReasons": {
"type": "array",
"items": {
"type": "string"
}
},
"verifiedAt": {
"type": "string"
}
}
}UploadIntentRequest
{
"type": "object",
"additionalProperties": false,
"required": [
"filename",
"declaredMime",
"declaredBytes"
],
"properties": {
"filename": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"declaredMime": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"example": "image/jpeg"
},
"declaredBytes": {
"type": "integer",
"minimum": 1,
"maximum": 524288000
},
"width": {
"type": "number",
"minimum": 0
},
"height": {
"type": "number",
"minimum": 0
},
"durationMs": {
"type": "number",
"minimum": 0
}
}
}UploadIntent
{
"type": "object",
"required": [
"assetId",
"sessionId",
"objectKey",
"method",
"expiresAt",
"maxBytes"
],
"description": "50 MB 미만 파일은 수명이 짧은 `uploadUrl`과 필요한 `headers`가 담긴 `method: presigned_put`을 반환해요. 50 MB 이상 파일은 `partSizeBytes`와 presigned 파트 URL의 `parts` 배열이 담긴 `method: multipart_initiated`를 반환해요; 각 파트를 업로드한 후 모든 파트의 ETag 영수증으로 확정하세요.\n",
"properties": {
"assetId": {
"type": "string",
"format": "uuid"
},
"sessionId": {
"type": "string"
},
"objectKey": {
"type": "string",
"description": "Opaque storage key; never a public URL"
},
"method": {
"type": "string",
"enum": [
"presigned_put",
"multipart_initiated"
]
},
"uploadUrl": {
"type": "string",
"description": "Short-lived; upload bytes directly with the documented method"
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Required request headers for the presigned PUT (e.g. content-type)"
},
"partSizeBytes": {
"type": "integer",
"description": "Required part size for multipart uploads"
},
"parts": {
"type": "array",
"description": "Presigned part URLs (multipart_initiated only); request fresh pages when they expire",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"partNumber",
"url",
"expiresAt"
],
"properties": {
"partNumber": {
"type": "integer",
"minimum": 1
},
"url": {
"type": "string"
},
"expiresAt": {
"type": "string"
}
}
}
},
"expiresAt": {
"type": "string"
},
"maxBytes": {
"type": "integer"
}
}
}UploadIntentResponse
{
"allOf": [
{
"$ref": "#/components/schemas/UploadIntent"
},
{
"type": "object",
"required": [
"requestId"
],
"properties": {
"requestId": {
"type": "string"
}
}
}
]
}TikTokCreatorSettings
{
"type": "object",
"additionalProperties": false,
"required": [
"privacyLevels",
"maxDurationSeconds",
"allowComments",
"allowDuet",
"allowStitch",
"directPublishingAllowed",
"inboxAllowed",
"nativeAccountId"
],
"properties": {
"privacyLevels": {
"type": "array",
"items": {
"type": "string",
"enum": [
"PUBLIC_TO_EVERYONE",
"MUTUAL_FOLLOW_FRIENDS",
"FOLLOWER_OF_CREATOR",
"SELF_ONLY"
]
}
},
"maxDurationSeconds": {
"type": "number",
"exclusiveMinimum": 0
},
"allowComments": {
"type": "boolean"
},
"allowDuet": {
"type": "boolean"
},
"allowStitch": {
"type": "boolean"
},
"directPublishingAllowed": {
"type": "boolean"
},
"inboxAllowed": {
"type": "boolean"
},
"nativeAccountId": {
"type": "string"
},
"creatorName": {
"type": "string"
},
"creatorAvatarUrl": {
"type": "string",
"format": "uri"
}
}
}MediaStatus
{
"type": "object",
"required": [
"id",
"originalName",
"mimeType",
"bytes",
"uploadState",
"createdAt",
"deletionState"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"originalName": {
"type": "string"
},
"mimeType": {
"type": "string"
},
"bytes": {
"type": "integer"
},
"uploadState": {
"type": "string",
"enum": [
"pending",
"uploading",
"finalized",
"rejected"
]
},
"createdAt": {
"type": "string"
},
"deleteAfter": {
"type": [
"string",
"null"
],
"description": "Dynamic deletion date, or null while kept for scheduled posts."
},
"deletionState": {
"type": "string",
"enum": [
"active",
"deleting",
"deleted"
]
}
}
}FinalizeRequest
{
"type": "object",
"additionalProperties": false,
"required": [
"sessionId"
],
"description": "호출자가 주장하는 관찰된 사실(바이트/MIME/체크섬)은 받아들이지 않아요: 서버가 불변인 최종(FINAL) 사본을 직접 검사해요. 멀티파트 업로드에는 모든 파트의 ETag 영수증이 포함돼야 해요.\n",
"properties": {
"sessionId": {
"type": "string",
"format": "uuid"
},
"multipart": {
"type": "object",
"additionalProperties": false,
"required": [
"parts"
],
"properties": {
"parts": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"partNumber",
"etag"
],
"properties": {
"partNumber": {
"type": "integer",
"minimum": 1
},
"etag": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
}
}
}
}
}
}
}FinalizeResult
{
"type": "object",
"required": [
"assetId",
"finalizeOperationId",
"bytes"
],
"properties": {
"assetId": {
"type": "string",
"format": "uuid"
},
"finalizeOperationId": {
"type": "string"
},
"bytes": {
"type": "integer"
},
"expiresAt": {
"type": [
"string",
"null"
]
}
}
}DraftInput
{
"type": "object",
"additionalProperties": false,
"required": [
"caption",
"destinations"
],
"properties": {
"caption": {
"type": "string",
"maxLength": 70000
},
"mediaIds": {
"type": "array",
"maxItems": 10,
"items": {
"type": "string",
"format": "uuid"
},
"default": []
},
"brandFolderId": {
"type": [
"string",
"null"
],
"format": "uuid",
"default": null
},
"destinations": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"$ref": "#/components/schemas/DraftDestination"
}
}
}
}DraftDestination
{
"type": "object",
"additionalProperties": false,
"required": [
"accountId",
"format"
],
"properties": {
"accountId": {
"type": "string",
"format": "uuid"
},
"format": {
"type": "string",
"enum": [
"text",
"single_image",
"image_set",
"video"
]
},
"overrides": {
"type": "object",
"additionalProperties": false,
"properties": {
"caption": {
"type": "string"
},
"mediaIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
},
"title": {
"type": "string"
},
"options": {
"type": "object",
"additionalProperties": true,
"description": "Validated against an allowlisted per-network schema; never a raw vendor bag."
}
}
}
}
}DraftUpdateInput
{
"allOf": [
{
"$ref": "#/components/schemas/DraftInput"
},
{
"type": "object",
"required": [
"expectedVersion"
],
"properties": {
"expectedVersion": {
"type": "integer",
"minimum": 1
}
}
}
]
}DraftSaveResult
{
"type": "object",
"required": [
"postId",
"version",
"createdAt",
"updatedAt"
],
"properties": {
"postId": {
"type": "string",
"format": "uuid"
},
"version": {
"type": "integer"
},
"createdAt": {
"type": "string"
},
"updatedAt": {
"type": "string"
}
}
}PostListItem
{
"type": "object",
"required": [
"postId",
"version",
"status",
"updatedAt"
],
"properties": {
"postId": {
"type": "string"
},
"version": {
"type": "integer"
},
"status": {
"type": "string"
},
"updatedAt": {
"type": "string"
}
}
}ValidationResult
{
"type": "object",
"required": [
"valid",
"revisionVersion",
"destinationResults"
],
"properties": {
"valid": {
"type": "boolean"
},
"revisionVersion": {
"type": "integer"
},
"destinationResults": {
"type": "array",
"items": {
"type": "object",
"required": [
"accountId",
"valid",
"requiresAction"
],
"properties": {
"accountId": {
"type": "string"
},
"valid": {
"type": "boolean"
},
"requiresAction": {
"type": "boolean",
"description": "True when the network requires an explicit human/consent step."
},
"errors": {
"type": "array",
"items": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"field": {
"type": "string"
},
"message": {
"type": "string"
}
}
}
},
"warnings": {
"type": "array",
"items": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
}
}
}
}
}
}
}
}AcceptedOperation
{
"type": "object",
"required": [
"revisionId",
"version",
"operationId",
"deliveryIds",
"scheduledAt",
"timezone",
"requestId"
],
"properties": {
"revisionId": {
"type": "string"
},
"version": {
"type": "integer"
},
"operationId": {
"type": "string"
},
"deliveryIds": {
"type": "array",
"items": {
"type": "string"
}
},
"scheduledAt": {
"type": "string"
},
"timezone": {
"type": "string"
},
"requestId": {
"type": "string"
},
"warnings": {
"type": "array",
"description": "Non-blocking notices preserved on replay, including key_expires_before_schedule when a key expires at or before dispatch.",
"items": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"field": {
"type": "string"
},
"message": {
"type": "string"
}
}
}
}
}
}ScheduleRequest
{
"type": "object",
"additionalProperties": false,
"required": [
"scheduledAt",
"timezone",
"expectedVersion"
],
"properties": {
"scheduledAt": {
"type": "string",
"format": "date-time",
"example": "2027-01-12T15:00:00Z"
},
"timezone": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"example": "America/Indiana/Indianapolis"
},
"expectedVersion": {
"type": "integer",
"minimum": 1
},
"revisionId": {
"type": [
"string",
"null"
],
"description": "Must be null in V1 (schedules the current revision); non-null is rejected."
}
}
}PostStatus
{
"type": "object",
"required": [
"postId",
"version",
"status",
"deliveries"
],
"properties": {
"postId": {
"type": "string"
},
"version": {
"type": "integer"
},
"status": {
"type": "string",
"enum": [
"draft",
"scheduled",
"in_progress",
"published",
"partially_published",
"needs_attention",
"canceled"
]
},
"deliveries": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"accountId": {
"type": "string"
},
"network": {
"type": "string"
},
"state": {
"type": "string"
},
"dueAt": {
"type": "string"
},
"nativePostUrl": {
"type": [
"string",
"null"
],
"description": "Only after a confirmed result."
},
"unresolvedExternalOutcome": {
"type": "boolean"
},
"cancelRequestedAt": {
"type": [
"string",
"null"
]
},
"retryCount": {
"type": "integer"
},
"publishedAt": {
"type": [
"string",
"null"
]
}
}
}
}
}
}Usage
{
"type": "object",
"description": "이 스키마 어디에도 남은 게시 카운터는 존재하지 않아요: 모든 유료 플랜에서 게시는 무제한이에요. 활동 숫자는 운영 지표예요.\n",
"required": [
"plan",
"accounts",
"members",
"storage",
"scheduling",
"rateLimit",
"activity"
],
"properties": {
"plan": {
"type": "object",
"required": [
"id",
"label",
"status"
],
"properties": {
"id": {
"type": "string",
"enum": [
"trial",
"creator",
"studio",
"operator"
]
},
"label": {
"type": "string"
},
"version": {
"type": "integer"
},
"interval": {
"type": [
"string",
"null"
],
"enum": [
"month",
"year",
null
]
},
"status": {
"type": "string"
},
"paidThrough": {
"type": [
"string",
"null"
]
},
"trialEndsAt": {
"type": [
"string",
"null"
]
}
}
},
"accounts": {
"type": "object",
"required": [
"connected",
"reserved",
"maxConnected"
],
"properties": {
"connected": {
"type": "integer"
},
"reserved": {
"type": "integer"
},
"maxConnected": {
"type": "integer"
}
}
},
"members": {
"type": "object",
"required": [
"active",
"max"
],
"properties": {
"active": {
"type": "integer"
},
"max": {
"type": "integer"
}
}
},
"storage": {
"type": "object",
"required": [
"activeBytes",
"reservedBytes",
"maxActiveBytes"
],
"properties": {
"activeBytes": {
"type": "integer"
},
"reservedBytes": {
"type": "integer"
},
"maxActiveBytes": {
"type": "integer"
}
}
},
"scheduling": {
"type": "object",
"required": [
"horizonDays"
],
"properties": {
"horizonDays": {
"type": "integer",
"example": 90
}
}
},
"rateLimit": {
"type": "object",
"required": [
"requestsPerMinute",
"note"
],
"properties": {
"requestsPerMinute": {
"type": "integer",
"example": 120
},
"note": {
"type": "string",
"example": "Technical speed limit: not a posting allowance."
}
}
},
"activity": {
"type": "object",
"description": "Operational metrics only; never an allowance or balance.",
"required": [
"deliveriesAttemptedLast30Days",
"deliveriesPublishedLast30Days"
],
"properties": {
"deliveriesAttemptedLast30Days": {
"type": "integer"
},
"deliveriesPublishedLast30Days": {
"type": "integer"
}
}
}
}
}CreateWebhookRequest
{
"type": "object",
"additionalProperties": false,
"required": [
"url"
],
"properties": {
"url": {
"type": "string",
"format": "uri",
"example": "https://example.com/hooks/autoposted"
},
"eventTypes": {
"oneOf": [
{
"type": "string",
"const": "all"
},
{
"type": "array",
"minItems": 1,
"items": {
"type": "string"
}
}
],
"description": "Omit or \"all\" for every event; an array filters by event type."
},
"description": {
"type": "string"
}
}
}WebhookEndpoint
{
"type": "object",
"required": [
"id",
"url",
"eventTypes",
"enabled",
"createdAt"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"url": {
"type": "string",
"format": "uri"
},
"eventTypes": {
"oneOf": [
{
"type": "string",
"const": "all"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
},
"enabled": {
"type": "boolean"
},
"verifiedAt": {
"type": [
"string",
"null"
]
},
"createdAt": {
"type": "string"
}
}
}