개발자 문서
개발자 문서

블로그 글 본문 보관

블로그 글쓰기 액션에 입력할 content_artifact_ref 를 받는 본문 보관, 확인, 삭제 방법입니다.

경로/v1/naver/content, /v1/tistory/content
인증HTTP Basic
기관 호출없음

언제 쓰나요

블로그 글을 임시저장, 수정, 발행하는 액션은 글 본문을 작업 요청에 직접 싣지 않습니다.

본문 보관은 기관을 호출하지 않고 작업을 만들지 않으며 사용 토큰을 쓰지 않습니다.

본문을 사용하는 액션

기관보관 경로actionblocks
네이버 블로그POST /v1/naver/contentnaver.blog.owner_post.update받음
네이버 블로그POST /v1/naver/contentnaver.blog.post_via_retired_api.create받음
네이버 블로그POST /v1/naver/contentnaver.blog.post_via_retired_api.publish받음
티스토리POST /v1/tistory/contenttistory.retired_openapi.create받음
티스토리POST /v1/tistory/contenttistory.retired_openapi.publish받음
티스토리POST /v1/tistory/contenttistory.retired_openapi.update받음

사용 순서

  1. 본문 보관

    본문을 사용할 action 과 content 를 POST 로 입력합니다.

  2. 참조 입력

    201 응답의 content_artifact_ref 를 작업 요청 params 의 document.content_artifact_ref 에 그대로 입력합니다.

  3. 같은 조직과 환경에서 사용

    보관한 본문은 보관한 조직과 환경(X-Env-Scope)에 묶입니다. 작업도 같은 환경으로 요청합니다. 데모 단계 키는 real_test, 요금제를 시작한 키는 production 입니다.

  4. 만료 전에 사용

    보관 기간은 운영 보관 정책이 정합니다. 응답의 expires_at 이 지나면 그 참조는 쓸 수 없으니 본문을 다시 보관합니다.

요청 헤더

필드타입필수설명예시
Authorizationstring필수API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.—
X-Env-Scopestring필수호출 환경입니다.—
Content-TypestringPOST 만요청 본문 형식입니다.—

요청 본문

필드타입필수설명예시
actionstring필수이 본문을 사용할 액션입니다. 위 표에서 그 경로의 action 만 받습니다.naver.blog.owner_post.update
contentobject필수글 본문입니다. body_paragraphs 는 필수이고 title, tags, category, blocks 는 선택입니다. 모르는 칸이 있으면 400 으로 거절합니다. 칸의 형식과 blocks 의 구조는 아래 전체 스키마를 확인하세요.—

요청 본문 전체 스키마

json
{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "naver.blog.owner_post.update",
        "naver.blog.post_via_retired_api.create",
        "naver.blog.post_via_retired_api.publish"
      ],
      "description": "이 본문을 사용할 실제 임시저장 액션입니다."
    },
    "content": {
      "type": "object",
      "properties": {
        "title": {
          "type": "string"
        },
        "body_paragraphs": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "string"
          }
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "category": {
          "type": "string"
        },
        "blocks": {
          "type": "array",
          "maxItems": 200,
          "description": "선택. 본문 레이아웃 블록(위에서 아래 순서). 네이버 블로그와 티스토리는 소제목, 인용, 목록, 표, 글자 색, 링크, 이미지로 그대로 옮긴다. image 블록은 prompt(글을 저장할 때 AI 가 이미지를 만든다)와 url(고객의 공개 https 이미지 주소, 저장할 때 받아 와 올린다) 중 하나를 넣고, 블록을 둔 자리에 이미지가 들어간다(글당 최대 10장). blocks 를 쓰더라도 body_paragraphs(평문)는 함께 넣는다.",
          "items": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "paragraph"
                    ]
                  },
                  "runs": {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                      "type": "object",
                      "properties": {
                        "text": {
                          "type": "string"
                        },
                        "bold": {
                          "type": "boolean"
                        },
                        "italic": {
                          "type": "boolean"
                        },
                        "color": {
                          "type": "string",
                          "pattern": "^#[0-9a-fA-F]{6}$"
                        },
                        "link": {
                          "type": "string",
                          "pattern": "^https?://\\S+$"
                        }
                      },
                      "required": [
                        "text"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "align": {
                    "type": "string",
                    "enum": [
                      "center",
                      "left"
                    ]
                  }
                },
                "required": [
                  "type",
                  "runs"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "heading"
                    ]
                  },
                  "text": {
                    "type": "string",
                    "minLength": 1
                  }
                },
                "required": [
                  "type",
                  "text"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "quote"
                    ]
                  },
                  "text": {
                    "type": "string",
                    "minLength": 1
                  }
                },
                "required": [
                  "type",
                  "text"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "bullets"
                    ]
                  },
                  "items": {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                      "type": "array",
                      "minItems": 1,
                      "items": {
                        "type": "object",
                        "properties": {
                          "text": {
                            "type": "string"
                          },
                          "bold": {
                            "type": "boolean"
                          },
                          "italic": {
                            "type": "boolean"
                          },
                          "color": {
                            "type": "string",
                            "pattern": "^#[0-9a-fA-F]{6}$"
                          },
                          "link": {
                            "type": "string",
                            "pattern": "^https?://\\S+$"
                          }
                        },
                        "required": [
                          "text"
                        ],
                        "additionalProperties": false
                      }
                    }
                  }
                },
                "required": [
                  "type",
                  "items"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "table"
                    ]
                  },
                  "rows": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 30,
                    "items": {
                      "type": "array",
                      "minItems": 1,
                      "maxItems": 6,
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "header_row": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "type",
                  "rows"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "image"
                    ]
                  },
                  "url": {
                    "type": "string",
                    "pattern": "^https://\\S+$",
                    "maxLength": 2048
                  },
                  "alt": {
                    "type": "string"
                  }
                },
                "required": [
                  "type",
                  "url"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "image"
                    ]
                  },
                  "prompt": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 1000
                  },
                  "alt": {
                    "type": "string"
                  }
                },
                "required": [
                  "type",
                  "prompt"
                ],
                "additionalProperties": false
              }
            ]
          }
        }
      },
      "required": [
        "body_paragraphs"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "action",
    "content"
  ],
  "additionalProperties": false
}

보관 요청 예시

bash
curl --request POST 'https://api.xdata.kr/v1/naver/content' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header 'Content-Type: application/json' \
  --data '{"action":"naver.blog.owner_post.update","content":{"title":"가을 신메뉴 안내","body_paragraphs":["이번 주부터 가을 신메뉴를 판매합니다.","매장과 온라인 주문 모두 가능합니다."],"tags":["신메뉴","가을"]}}'

201 응답 예시

json
{
  "purpose": "blog_content_v1",
  "content_type": "application/json",
  "size_bytes": 208,
  "sha256": "cc1bc878b78910d29fc4070581a5054ad4854e9a4effe2c6725bb86bd4430da0",
  "created_at": "2026-09-01T10:00:00+09:00",
  "expires_at": "2026-09-08T10:00:00+09:00",
  "reused": false,
  "content_artifact_ref": "art_01JC8YH8R0E1ABCDEFGHJKMN01"
}

201 응답 필드

필드타입필수설명예시
content_artifact_refstring항상보관한 본문의 참조입니다. 작업 요청의 document.content_artifact_ref 에 입력합니다.—
purposestring항상본문 종류입니다. 지금은 blog_content_v1 하나입니다.—
content_typestring항상보관한 형식입니다. 지금은 application/json 입니다.—
size_bytesinteger항상정규화해 보관한 본문의 바이트 수입니다.—
sha256string항상정규화해 보관한 본문의 SHA-256 입니다.—
created_atstring항상보관한 시각입니다(한국 시간, ISO 8601).—
expires_atstring항상이 참조를 쓸 수 있는 마지막 시각입니다. 예시의 날짜 간격은 예시일 뿐이며 실제 기간은 운영 보관 정책이 정합니다.—
reusedboolean항상같은 조직과 환경에 같은 본문이 만료 전으로 이미 있으면 true 이고, 새로 만들지 않고 그 참조와 expires_at 을 돌려줍니다.—

보관한 본문 확인과 삭제

GET {보관 경로}/{content_artifact_ref} 는 보관한 본문을 { content_artifact_ref, content } 로 돌려줍니다.

DELETE {보관 경로}/{content_artifact_ref} 는 보관한 본문을 지우고 204 를 돌려줍니다.

이 경로의 응답은 모두 캐시하지 않습니다(Cache-Control: no-store).

확인 요청 예시

bash
curl 'https://api.xdata.kr/v1/naver/content/art_01JC8YH8R0E1ABCDEFGHJKMN01' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test'

200 응답 예시

json
{
  "content_artifact_ref": "art_01JC8YH8R0E1ABCDEFGHJKMN01",
  "content": {
    "title": "가을 신메뉴 안내",
    "body_paragraphs": [
      "이번 주부터 가을 신메뉴를 판매합니다.",
      "매장과 온라인 주문 모두 가능합니다."
    ],
    "tags": [
      "신메뉴",
      "가을"
    ],
    "category": ""
  }
}

오류

HTTPerror.codeerror.provider_error_referror.message메서드
400VALIDATION_INVALID_FIELDinput_artifacts.content_invalid게시할 본문 형식을 확인해 주세요.POST
404RESOURCE_NOT_FOUNDinput_artifacts.content_not_found본문을 찾을 수 없습니다. 본문을 다시 준비해 주세요.GET
409RESOURCE_CONFLICTinput_artifacts.content_limit_reached보관 중인 본문이 많습니다. 사용하지 않는 본문을 지운 뒤 다시 시도해 주세요.POST
503SERVICE_UNAVAILABLEinput_artifacts.content_store_unavailable본문 저장 기능이 아직 준비되지 않았습니다. 잠시 후 다시 시도해 주세요.POST, GET, DELETE

오류 응답의 모양과 그 밖의 코드(인증, 권한, 환경, 기능 꺼짐)는 오류 코드와 같습니다.