블로그 글 본문 보관
블로그 글쓰기 액션에 입력할 content_artifact_ref 를 받는 본문 보관, 확인, 삭제 방법입니다.
| 경로 | /v1/naver/content, /v1/tistory/content |
|---|---|
| 인증 | HTTP Basic |
| 기관 호출 | 없음 |
언제 쓰나요
블로그 글을 임시저장, 수정, 발행하는 액션은 글 본문을 작업 요청에 직접 싣지 않습니다.먼저 이 경로로 본문을 보관하고, 응답의 content_artifact_ref 를 작업 요청의 document.content_artifact_ref 에 입력합니다.
본문 보관은 기관을 호출하지 않고 작업을 만들지 않으며 사용 토큰을 쓰지 않습니다.다만 본문을 사용할 액션을 쓸 수 있는 계정이어야 하고, 그 쓰기 기능이 지금 열려 있어야 보관됩니다. 이 조건의 거절은 오류 코드의 인증, 권한, 기능 꺼짐 코드로 옵니다.
본문을 사용하는 액션
| 기관 | 보관 경로 | action | blocks |
|---|---|---|---|
| 네이버 블로그 | POST /v1/naver/content | naver.blog.owner_post.update | 받음 |
| 네이버 블로그 | POST /v1/naver/content | naver.blog.post_via_retired_api.create | 받음 |
| 네이버 블로그 | POST /v1/naver/content | naver.blog.post_via_retired_api.publish | 받음 |
| 티스토리 | POST /v1/tistory/content | tistory.retired_openapi.create | 받음 |
| 티스토리 | POST /v1/tistory/content | tistory.retired_openapi.publish | 받음 |
| 티스토리 | POST /v1/tistory/content | tistory.retired_openapi.update | 받음 |
사용 순서
- 본문 보관
본문을 사용할 action 과 content 를 POST 로 입력합니다.액션의 기관과 같은 경로(네이버는 /v1/naver/content, 티스토리는 /v1/tistory/content)를 씁니다.
- 참조 입력
201 응답의 content_artifact_ref 를 작업 요청 params 의 document.content_artifact_ref 에 그대로 입력합니다.공개 URL 이나 다른 값은 받지 않습니다.
- 같은 조직과 환경에서 사용
보관한 본문은 보관한 조직과 환경(X-Env-Scope)에 묶입니다. 작업도 같은 환경으로 요청합니다. 데모 단계 키는 real_test, 요금제를 시작한 키는 production 입니다.
- 만료 전에 사용
보관 기간은 운영 보관 정책이 정합니다. 응답의 expires_at 이 지나면 그 참조는 쓸 수 없으니 본문을 다시 보관합니다.
요청 헤더
| 필드 | 타입 | 필수 | 설명 | 예시 |
|---|---|---|---|---|
| Authorization | string | 필수 | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | — |
| X-Env-Scope | string | 필수 | 호출 환경입니다. | — |
| Content-Type | string | POST 만 | 요청 본문 형식입니다. | — |
요청 본문
| 필드 | 타입 | 필수 | 설명 | 예시 |
|---|---|---|---|---|
| action | string | 필수 | 이 본문을 사용할 액션입니다. 위 표에서 그 경로의 action 만 받습니다. | naver.blog.owner_post.update |
| content | object | 필수 | 글 본문입니다. body_paragraphs 는 필수이고 title, tags, category, blocks 는 선택입니다. 모르는 칸이 있으면 400 으로 거절합니다. 칸의 형식과 blocks 의 구조는 아래 전체 스키마를 확인하세요. | — |
요청 본문 전체 스키마
{
"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
}보관 요청 예시
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 응답 예시
{
"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_ref | string | 항상 | 보관한 본문의 참조입니다. 작업 요청의 document.content_artifact_ref 에 입력합니다. | — |
| purpose | string | 항상 | 본문 종류입니다. 지금은 blog_content_v1 하나입니다. | — |
| content_type | string | 항상 | 보관한 형식입니다. 지금은 application/json 입니다. | — |
| size_bytes | integer | 항상 | 정규화해 보관한 본문의 바이트 수입니다. | — |
| sha256 | string | 항상 | 정규화해 보관한 본문의 SHA-256 입니다. | — |
| created_at | string | 항상 | 보관한 시각입니다(한국 시간, ISO 8601). | — |
| expires_at | string | 항상 | 이 참조를 쓸 수 있는 마지막 시각입니다. 예시의 날짜 간격은 예시일 뿐이며 실제 기간은 운영 보관 정책이 정합니다. | — |
| reused | boolean | 항상 | 같은 조직과 환경에 같은 본문이 만료 전으로 이미 있으면 true 이고, 새로 만들지 않고 그 참조와 expires_at 을 돌려줍니다. | — |
보관한 본문 확인과 삭제
GET {보관 경로}/{content_artifact_ref} 는 보관한 본문을 { content_artifact_ref, content } 로 돌려줍니다.만료되었거나 지운 본문, 다른 조직이나 다른 환경의 참조는 404 입니다.
DELETE {보관 경로}/{content_artifact_ref} 는 보관한 본문을 지우고 204 를 돌려줍니다.없거나 이미 지운 참조도 204 이며, 만료된 본문도 지울 수 있습니다. 본문을 지워도 이미 기관에 저장된 글은 지워지지 않습니다.
이 경로의 응답은 모두 캐시하지 않습니다(Cache-Control: no-store).
확인 요청 예시
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 응답 예시
{
"content_artifact_ref": "art_01JC8YH8R0E1ABCDEFGHJKMN01",
"content": {
"title": "가을 신메뉴 안내",
"body_paragraphs": [
"이번 주부터 가을 신메뉴를 판매합니다.",
"매장과 온라인 주문 모두 가능합니다."
],
"tags": [
"신메뉴",
"가을"
],
"category": ""
}
}오류
| HTTP | error.code | error.provider_error_ref | error.message | 메서드 |
|---|---|---|---|---|
| 400 | VALIDATION_INVALID_FIELD | input_artifacts.content_invalid | 게시할 본문 형식을 확인해 주세요. | POST |
| 404 | RESOURCE_NOT_FOUND | input_artifacts.content_not_found | 본문을 찾을 수 없습니다. 본문을 다시 준비해 주세요. | GET |
| 409 | RESOURCE_CONFLICT | input_artifacts.content_limit_reached | 보관 중인 본문이 많습니다. 사용하지 않는 본문을 지운 뒤 다시 시도해 주세요. | POST |
| 503 | SERVICE_UNAVAILABLE | input_artifacts.content_store_unavailable | 본문 저장 기능이 아직 준비되지 않았습니다. 잠시 후 다시 시도해 주세요. | POST, GET, DELETE |
오류 응답의 모양과 그 밖의 코드(인증, 권한, 환경, 기능 꺼짐)는 오류 코드와 같습니다.400 은 본문의 칸과 형식을 고쳐 다시 요청하고, 409 는 쓰지 않는 본문을 DELETE 로 지운 뒤 다시 요청합니다. 503 은 잠시 후 다시 요청합니다.