API 레퍼런스

Spec Document

이 페이지의 내용

이 페이지는 공개 계약에서 생성하며 설명은 원문(한국어) 그대로 표시합니다.

Repository 소속 OpenAPI·AsyncAPI·Arazzo 원문, 구조 조회, OpenAPI의 API·Endpoint 두 단계 동기화.

Repository 소속 스펙 문서 목록#

GET /api/repositories/{repository_id}/spec-documents

원문을 제외하고 이름 UTF-8 바이트·ID 순서로 반환합니다. query는 허용하지 않습니다.

인증: 세션 쿠키 또는 Agent 토큰

Parameter

이름	위치	타입	필수	설명
`repository_id`	path	`string`	예	부모 Repository ID.

응답

상태	설명
`200`	성공. 빈 목록은 []
`400`	INVALID_REQUEST·INVALID_ID: JSON·미정의 필드·query·조건 헤더 구문·경로 ID 오류
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`404`	REPOSITORY_NOT_FOUND·REPOSITORY_EXTERNAL_IDENTITY_NOT_FOUND·SPEC_DOCUMENT_NOT_FOUND: 현재 Organization에 기록이 없습니다.
`405`	METHOD_NOT_ALLOWED
`409`	ORGANIZATION_REQUIRED·REPOSITORY_NAME_CONFLICT·REPOSITORY_URL_CONFLICT·REPOSITORY_EXTERNAL_IDENTITY_CONFLICT·REPOSITORY_IN_USE·SPEC_DOCUMENT_NAME_CONFLICT·REGISTRATION_KEY_CONFLICT
`500`	INTERNAL_ERROR

200 응답 본문

배열(SpecDocumentSummary[])이며 표는 항목의 필드입니다.

이름	타입	필수	설명
`api_id`	`string \| null`	예
`content_format`	`string`	예	JSON으로 읽히면 json, 아니면 YAML 단일 문서로 읽어 yaml 값: `json`, `yaml`
`created_at`	`string(date-time)`	예	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.
`description`	`string`	예	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`id`	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`kind`	`string`	예	원문 최상위의 같은 이름 필드에 버전 문자열이 있어야 합니다. 값: `openapi`, `asyncapi`, `arazzo`
`name`	`string`	예
`path`	`string`	예
`repository_id`	`string \| null`	예
`spec_version`	`string`	예	원문 최상위 버전 필드 값. 서버가 저장 시 판정합니다.
`summary`	`string`	예	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`updated_at`	`string(date-time)`	예	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.

스펙 문서 생성#

POST /api/repositories/{repository_id}/spec-documents

이름은 같은 Repository 안에서 대소문자를 무시하고 유일해야 합니다. 원문은 최상위 버전 필드만 확인하고 명세 전체 규칙·$ref는 검사하지 않습니다. 같은 등록 키와 입력은 200으로 기존 문서를 반환하며 다른 입력은 409 REGISTRATION_KEY_CONFLICT입니다.

인증: 세션 쿠키 또는 Agent 토큰

Parameter

이름	위치	타입	필수	설명
`repository_id`	path	`string`	예	부모 Repository ID.

요청 본문

application/json · 필수: 예

JSON 객체 하나. UTF-8·중복 키·미정의 필드·서버 소유 필드를 엄격히 검사하며 본문 최대 4 MiB.

타입: SpecDocumentCreate

이름	타입	필수	설명
`content`	`string`	예	JSON 또는 YAML 단일 문서 원문. UTF-8 1~1,048,576바이트이며 U+0000을 거부합니다. 바이트 그대로 보존합니다.
`description`	`string`	아니요	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`kind`	`string`	예	원문 최상위의 같은 이름 필드에 버전 문자열이 있어야 합니다. 값: `openapi`, `asyncapi`, `arazzo`
`name`	`string`	예	앞뒤 U+0020 공백 제거 후 1~200 유니코드 코드 포인트. 제어문자는 제거 전에 거부하며 범위는 U+0000~U+001F·U+007F~U+009F입니다. 다른 유니코드 공백·정규화는 적용하지 않습니다. 정규화 전 입력에는 maxLength 200을 적용하지 않습니다.
`path`	`string`	아니요	Repository 루트 기준 상대 경로. 앞뒤 U+0020 제거 후 0~1024자이며 제어문자·역슬래시·앞 `/`·빈·`.`·`..` segment를 거부합니다.
`expected_organization_id`	`string`	아니요	사전 확인한 Organization ID. 현재 요청 경계와 다르면 등록하지 않습니다.
`registration_key`	`string`	아니요	생성 시에만 받는 등록 재시도 키
`summary`	`string`	아니요	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.

응답

상태	설명
`200`	같은 등록 키·입력의 재시도
`201`	생성
`400`	INVALID_REQUEST·INVALID_ID: JSON·미정의 필드·query·조건 헤더 구문·경로 ID 오류
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`404`	REPOSITORY_NOT_FOUND·REPOSITORY_EXTERNAL_IDENTITY_NOT_FOUND·SPEC_DOCUMENT_NOT_FOUND: 현재 Organization에 기록이 없습니다.
`405`	METHOD_NOT_ALLOWED
`409`	ORGANIZATION_REQUIRED·REPOSITORY_NAME_CONFLICT·REPOSITORY_URL_CONFLICT·REPOSITORY_EXTERNAL_IDENTITY_CONFLICT·REPOSITORY_IN_USE·SPEC_DOCUMENT_NAME_CONFLICT·REGISTRATION_KEY_CONFLICT
`413`	PAYLOAD_TOO_LARGE: Repository 64 KiB, 스펙 문서 4 MiB 본문 상한
`415`	UNSUPPORTED_MEDIA_TYPE
`422`	VALIDATION_FAILED: 필수 값·타입·길이·문자·Git URL 문법·원문 형식 오류
`500`	INTERNAL_ERROR

200 응답 본문

타입: SpecDocument

이름	타입	필수	설명
`api_id`	`string \| null`	예
`content`	`string`	예	JSON 또는 YAML 단일 문서 원문. UTF-8 1~1,048,576바이트이며 U+0000을 거부합니다. 바이트 그대로 보존합니다.
`content_format`	`string`	예	JSON으로 읽히면 json, 아니면 YAML 단일 문서로 읽어 yaml 값: `json`, `yaml`
`created_at`	`string(date-time)`	예	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.
`description`	`string`	예	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`id`	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`kind`	`string`	예	원문 최상위의 같은 이름 필드에 버전 문자열이 있어야 합니다. 값: `openapi`, `asyncapi`, `arazzo`
`name`	`string`	예
`path`	`string`	예
`repository_id`	`string \| null`	예
`spec_version`	`string`	예	원문 최상위 버전 필드 값. 서버가 저장 시 판정합니다.
`summary`	`string`	예	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`updated_at`	`string(date-time)`	예	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.

스펙 문서 상세#

GET /api/spec-documents/{id}

인증: 세션 쿠키 또는 Agent 토큰

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예	대상 ID.
`If-None-Match`	header	`string`	아니요	상세 GET의 선택 조건. 태그 목록 또는 `*`와 약한 비교로 일치하면 304, 불일치하면 200입니다.

응답

상태	설명
`200`	성공. 원문 포함
`304`	If-None-Match 일치. 본문 없음
`400`	INVALID_REQUEST·INVALID_ID: JSON·미정의 필드·query·조건 헤더 구문·경로 ID 오류
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`404`	REPOSITORY_NOT_FOUND·REPOSITORY_EXTERNAL_IDENTITY_NOT_FOUND·SPEC_DOCUMENT_NOT_FOUND: 현재 Organization에 기록이 없습니다.
`405`	METHOD_NOT_ALLOWED
`409`	ORGANIZATION_REQUIRED·REPOSITORY_NAME_CONFLICT·REPOSITORY_URL_CONFLICT·REPOSITORY_EXTERNAL_IDENTITY_CONFLICT·REPOSITORY_IN_USE·SPEC_DOCUMENT_NAME_CONFLICT·REGISTRATION_KEY_CONFLICT
`500`	INTERNAL_ERROR

200 응답 본문

타입: SpecDocument

이름	타입	필수	설명
`api_id`	`string \| null`	예
`content`	`string`	예	JSON 또는 YAML 단일 문서 원문. UTF-8 1~1,048,576바이트이며 U+0000을 거부합니다. 바이트 그대로 보존합니다.
`content_format`	`string`	예	JSON으로 읽히면 json, 아니면 YAML 단일 문서로 읽어 yaml 값: `json`, `yaml`
`created_at`	`string(date-time)`	예	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.
`description`	`string`	예	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`id`	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`kind`	`string`	예	원문 최상위의 같은 이름 필드에 버전 문자열이 있어야 합니다. 값: `openapi`, `asyncapi`, `arazzo`
`name`	`string`	예
`path`	`string`	예
`repository_id`	`string \| null`	예
`spec_version`	`string`	예	원문 최상위 버전 필드 값. 서버가 저장 시 판정합니다.
`summary`	`string`	예	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`updated_at`	`string(date-time)`	예	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.

스펙 문서 전체 수정#

PUT /api/spec-documents/{id}

다른 Repository로 이동하지 않습니다. kind를 포함한 전체 필드를 바꾸며 원문 검사 규칙은 생성과 같습니다.

인증: 세션 쿠키 또는 Agent 토큰

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예	대상 ID.
`If-Match`	header	`string`	예	상세 GET의 단일 strong ETag. 누락 428, 다른 revision·ID·리소스 412, `*`·약한·복수 태그·잘못된 구문 400. 미존재 404가 조건 평가보다 우선합니다.

요청 본문

application/json · 필수: 예

JSON 객체 하나. UTF-8·중복 키·미정의 필드·서버 소유 필드를 엄격히 검사하며 본문 최대 4 MiB.

타입: SpecDocumentReplace

이름	타입	필수	설명
`kind`	`string`	예	원문 최상위의 같은 이름 필드에 버전 문자열이 있어야 합니다. 값: `openapi`, `asyncapi`, `arazzo`
`name`	`string`	예	앞뒤 U+0020 공백 제거 후 1~200 유니코드 코드 포인트. 제어문자는 제거 전에 거부하며 범위는 U+0000~U+001F·U+007F~U+009F입니다. 다른 유니코드 공백·정규화는 적용하지 않습니다. 정규화 전 입력에는 maxLength 200을 적용하지 않습니다.
`path`	`string`	예	Repository 루트 기준 상대 경로. 앞뒤 U+0020 제거 후 0~1024자이며 제어문자·역슬래시·앞 `/`·빈·`.`·`..` segment를 거부합니다.
`summary`	`string`	예	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	예	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`content`	`string`	예	JSON 또는 YAML 단일 문서 원문. UTF-8 1~1,048,576바이트이며 U+0000을 거부합니다. 바이트 그대로 보존합니다.

응답

상태	설명
`200`	성공
`400`	INVALID_REQUEST·INVALID_ID: JSON·미정의 필드·query·조건 헤더 구문·경로 ID 오류
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`404`	REPOSITORY_NOT_FOUND·REPOSITORY_EXTERNAL_IDENTITY_NOT_FOUND·SPEC_DOCUMENT_NOT_FOUND: 현재 Organization에 기록이 없습니다.
`405`	METHOD_NOT_ALLOWED
`409`	ORGANIZATION_REQUIRED·REPOSITORY_NAME_CONFLICT·REPOSITORY_URL_CONFLICT·REPOSITORY_EXTERNAL_IDENTITY_CONFLICT·REPOSITORY_IN_USE·SPEC_DOCUMENT_NAME_CONFLICT·REGISTRATION_KEY_CONFLICT
`412`	PRECONDITION_FAILED: 조회 이후 다른 쓰기가 성공했습니다.
`413`	PAYLOAD_TOO_LARGE: Repository 64 KiB, 스펙 문서 4 MiB 본문 상한
`415`	UNSUPPORTED_MEDIA_TYPE
`422`	VALIDATION_FAILED: 필수 값·타입·길이·문자·Git URL 문법·원문 형식 오류
`428`	PRECONDITION_REQUIRED: PUT·DELETE의 If-Match 누락
`500`	INTERNAL_ERROR

200 응답 본문

타입: SpecDocument

이름	타입	필수	설명
`api_id`	`string \| null`	예
`content`	`string`	예	JSON 또는 YAML 단일 문서 원문. UTF-8 1~1,048,576바이트이며 U+0000을 거부합니다. 바이트 그대로 보존합니다.
`content_format`	`string`	예	JSON으로 읽히면 json, 아니면 YAML 단일 문서로 읽어 yaml 값: `json`, `yaml`
`created_at`	`string(date-time)`	예	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.
`description`	`string`	예	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`id`	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`kind`	`string`	예	원문 최상위의 같은 이름 필드에 버전 문자열이 있어야 합니다. 값: `openapi`, `asyncapi`, `arazzo`
`name`	`string`	예
`path`	`string`	예
`repository_id`	`string \| null`	예
`spec_version`	`string`	예	원문 최상위 버전 필드 값. 서버가 저장 시 판정합니다.
`summary`	`string`	예	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`updated_at`	`string(date-time)`	예	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.

스펙 문서 삭제#

DELETE /api/spec-documents/{id}

이 문서를 출처로 둔 Endpoint·Workflow는 남기고 출처를 해제합니다. 실패한 삭제는 출처를 바꾸지 않습니다.

인증: 세션 쿠키 또는 Agent 토큰

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예	대상 ID.
`If-Match`	header	`string`	예	상세 GET의 단일 strong ETag. 누락 428, 다른 revision·ID·리소스 412, `*`·약한·복수 태그·잘못된 구문 400. 미존재 404가 조건 평가보다 우선합니다.

응답

상태	설명
`204`	삭제. 본문 없음
`400`	INVALID_REQUEST·INVALID_ID: JSON·미정의 필드·query·조건 헤더 구문·경로 ID 오류
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`404`	REPOSITORY_NOT_FOUND·REPOSITORY_EXTERNAL_IDENTITY_NOT_FOUND·SPEC_DOCUMENT_NOT_FOUND: 현재 Organization에 기록이 없습니다.
`405`	METHOD_NOT_ALLOWED
`409`	ORGANIZATION_REQUIRED·REPOSITORY_NAME_CONFLICT·REPOSITORY_URL_CONFLICT·REPOSITORY_EXTERNAL_IDENTITY_CONFLICT·REPOSITORY_IN_USE·SPEC_DOCUMENT_NAME_CONFLICT·REGISTRATION_KEY_CONFLICT
`412`	PRECONDITION_FAILED: 조회 이후 다른 쓰기가 성공했습니다.
`428`	PRECONDITION_REQUIRED: PUT·DELETE의 If-Match 누락
`500`	INTERNAL_ERROR

스펙 문서 구조 조회#

GET /api/spec-documents/{id}/view

Web 뷰어·stly spec-documents view용 JSON 구조입니다. 변환 실패도 200이며 value는 null, message에 안내를 담습니다. 외부 참조를 수집하지 않습니다.

인증: 세션 쿠키 또는 Agent 토큰

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예	대상 ID.
`If-None-Match`	header	`string`	아니요	상세 GET의 선택 조건. 태그 목록 또는 `*`와 약한 비교로 일치하면 304, 불일치하면 200입니다.

응답

상태	설명
`200`	성공
`304`	If-None-Match 일치. 본문 없음
`400`	INVALID_REQUEST·INVALID_ID: JSON·미정의 필드·query·조건 헤더 구문·경로 ID 오류
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`404`	REPOSITORY_NOT_FOUND·REPOSITORY_EXTERNAL_IDENTITY_NOT_FOUND·SPEC_DOCUMENT_NOT_FOUND: 현재 Organization에 기록이 없습니다.
`405`	METHOD_NOT_ALLOWED
`409`	ORGANIZATION_REQUIRED·REPOSITORY_NAME_CONFLICT·REPOSITORY_URL_CONFLICT·REPOSITORY_EXTERNAL_IDENTITY_CONFLICT·REPOSITORY_IN_USE·SPEC_DOCUMENT_NAME_CONFLICT·REGISTRATION_KEY_CONFLICT
`500`	INTERNAL_ERROR

200 응답 본문

타입: SpecDocumentView

이름	타입	필수	설명
`value`	`any`	예	원문을 JSON 값으로 바꾼 구조. 변환할 수 없으면 null입니다.
`source_etag`	`string`	예	변환에 사용한 원문의 ETag. 원문 상세 ETag와 다르면 구조를 표시하지 않습니다.
`message`	`string`	예	변환 실패 안내. 성공하면 빈 문자열입니다.

manifest 연결·식별·등록 키 준비(저장 없음)#

POST /api/spec-documents/manifest-plan

설정된 서버·현재 Organization과 manifest의 연결을 검증합니다. register는 클라이언트 등록 키를 새 항목에 준비하고, import·export는 document_id 또는 등록 키로 문서를 식별해 복구합니다. 실제 등록·반영 요청 전에 호출하며 서버 저장을 하지 않습니다.

인증: 세션 쿠키 또는 Agent 토큰

요청 본문

application/json · 필수: 예

타입: ManifestPlanRequest

이름	타입	필수	설명
`operation`	`string`	예	값: `register`, `import`, `export`
`path`	`string`	예
`manifest`	`string`	아니요	기존 structly.yaml 원문. register의 새 파일에서만 생략 가능.
`repository_id`	`string`	아니요	register에서 명시한 Repository. 기존 manifest와 다르면 거부합니다.
`registration_key`	`string`	아니요	클라이언트가 생성한 UUID. register에서 기존 항목의 키가 없을 때만 기록합니다.

응답

상태	설명
`200`	읽기 전용 manifest 준비 결과. 파일 저장은 클라이언트가 수행합니다.
`400`	400 오류.
`401`	401 오류.
`403`	403 오류.
`404`	404 오류.
`405`	405 오류.
`409`	409 오류.
`413`	413 오류.
`415`	415 오류.
`422`	422 오류.
`500`	500 오류.

200 응답 본문

타입: ManifestPlan

이름	타입	필수
`manifest`	`string`	예
`server`	`string`	예
`organization_id`	`string`	예
`repository_id`	`string \| null`	예
`document_id`	`string \| null`	예
`registration_key`	`string \| null`	예

승인 기반 OpenAPI export 계획#

POST /api/spec-documents/{id}/export-plan

읽기 전용 Snapshot에서 Catalog와 원문 정규형의 차이를 비교합니다. 승인한 API Metadata·Base URL·제공 Service(manifest)·Endpoint 요약·설명만 반영하고 그 밖의 차이는 unsupported로 보고합니다. 서버 Catalog·저장 원문은 변경하지 않습니다.

인증: 세션 쿠키 또는 Agent 토큰

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예

요청 본문

application/json · 필수: 예

타입: ExportPlanRequest

이름	타입	필수	설명
`content`	`string`	아니요	로컬 OpenAPI 원문. 생략하면 저장 원문을 사용하며 export는 서버 원문을 바꾸지 않습니다.
`manifest`	`string`	예	structly.yaml v1 원문.
`path`	`string`	예	manifest documents의 대상 상대 경로.

응답

상태	설명
`200`	서버 저장 없는 결과. ETag와 plan_token은 동일한 export 계획 토큰입니다.
`400`	400 오류.
`401`	401 오류.
`403`	403 오류.
`404`	404 오류.
`405`	405 오류.
`409`	409 오류.
`413`	413 오류.
`415`	415 오류.
`422`	422 오류.
`500`	500 오류.

200 응답 본문

타입: ExportPlan

이름	타입	필수	설명
`plan_token`	`string`	예	"export-plan:<sha256>". 관련 revision·제출 원문·manifest 대상 항목을 보호합니다.
`applicable`	`boolean`	예	변환·식별 오류가 없으면 true. unsupported는 지원 changes의 반영을 막지 않습니다.
`changes`	`ExportChange[]`	예
`unsupported`	`ExportUnsupported[]`	예
`warnings`	`SyncIssue[]`	예
`errors`	`SyncIssue[]`	예
`manifest`	`string`	예
`content`	`string`	아니요	export 반영 응답의 새 원문. JSON·YAML 형식을 유지하며 서버에 저장하지 않습니다.

승인한 Catalog 값을 OpenAPI 원문으로 반환#

POST /api/spec-documents/{id}/export

인증: 세션 쿠키 또는 Agent 토큰

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예
`If-Match`	header	`string`	예	같은 본문(approved 제외)으로 받은 import-plan의 plan_token. 누락 428, 변경된 계획 412, 약한·복수·잘못된 태그 400.

요청 본문

application/json · 필수: 예

타입: ExportRequest

이름	타입	필수	설명
`content`	`string`	아니요	로컬 OpenAPI 원문. 생략하면 저장 원문을 사용하며 export는 서버 원문을 바꾸지 않습니다.
`manifest`	`string`	예	structly.yaml v1 원문.
`path`	`string`	예	manifest documents의 대상 상대 경로.
`approved`	`string[]`	예	지원 changes에서 승인할 ID. 빈 배열은 원문을 유지하고 식별 매핑만 복구합니다.

응답

상태	설명
`200`	서버 저장 없는 결과. ETag와 plan_token은 동일한 export 계획 토큰입니다.
`400`	400 오류.
`401`	401 오류.
`403`	403 오류.
`404`	404 오류.
`405`	405 오류.
`409`	409 오류.
`412`	412 오류.
`413`	413 오류.
`415`	415 오류.
`422`	422 오류.
`428`	428 오류.
`500`	500 오류.

200 응답 본문

타입: ExportResult

이름	타입	필수	설명
`plan_token`	`string`	예	"export-plan:<sha256>". 관련 revision·제출 원문·manifest 대상 항목을 보호합니다.
`applicable`	`boolean`	예	변환·식별 오류가 없으면 true. unsupported는 지원 changes의 반영을 막지 않습니다.
`changes`	`ExportChange[]`	예
`unsupported`	`ExportUnsupported[]`	예
`warnings`	`SyncIssue[]`	예
`errors`	`SyncIssue[]`	예
`manifest`	`string`	예
`content`	`string`	예	export 반영 응답의 새 원문. JSON·YAML 형식을 유지하며 서버에 저장하지 않습니다.

OpenAPI import 계획#

POST /api/spec-documents/{id}/import-plan

제출 원문을 현재 변환 규칙의 Catalog 정규형으로 바꿔 현재 값과 비교합니다. 저장하지 않으며 변경 ID별 차이·덮어쓸 필드·함께 승인할 변경을 반환합니다. 마지막 동기화 기준값과 비교하지 않습니다.

인증: 세션 쿠키 또는 Agent 토큰

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예

요청 본문

application/json · 필수: 예

타입: ImportPlanRequest

이름	타입	필수	설명
`content`	`string`	예	제출할 OpenAPI 원문. 반영하면 저장 원문도 이 값으로 교체합니다.
`manifest`	`string`	예	structly.yaml 원문(version 1). 인증 정보·미정의 키·중복 키·별칭은 거부합니다.
`path`	`string`	예	manifest documents의 대상 path.
`api`	`object`	아니요	최초 반영의 API 대상. 이미 연결된 문서는 생략하거나 같은 API ID만 허용합니다.
`service`	`null \| object`	아니요	제공 Service 선택. null은 명시적 미연결. 생략하면 manifest의 service_id를 쓰며, 최초 반영은 둘 중 하나가 필요합니다.
`rename`	`object`	아니요	사라진 매핑 operationId → 새 operationId. rename_candidate를 같은 Endpoint의 이름 변경으로 확정합니다.
`link`	`object`	아니요	operationId → 연결할 출처 없는 Endpoint ID. link_candidate를 확정합니다.
`recreate`	`string[]`	아니요	manifest의 Endpoint ID가 없어진 operation을 새로 만들 operationId.

응답

상태	설명
`200`	import 계획. 변환·식별 오류도 errors에 모읍니다.
`400`	400 오류.
`401`	401 오류.
`403`	403 오류.
`404`	404 오류.
`405`	405 오류.
`409`	409 오류.
`413`	413 오류.
`415`	415 오류.
`422`	422 오류.
`500`	500 오류.

200 응답 본문

타입: ImportPlan

이름	타입	필수	설명
`plan_token`	`string`	예	"import-plan:<sha256>". 대상·후보·이동 원천의 관련 revision과 요청 옵션 범위의 토큰입니다.
`applicable`	`boolean`	예	변환·식별 오류가 없으면 true. 승인 범위와 무관한 operation의 오류도 반영을 막습니다.
`api_id`	`string`	아니요
`changes`	`ImportChange[]`	예
`items`	`ImportItem[]`	예
`deletion_candidates`	`object[]`	예	원문에서 사라진 이 문서 출처 Endpoint. 삭제·출처 해제·이동은 별도로 확정합니다.
`warnings`	`SyncIssue[]`	예
`errors`	`SyncIssue[]`	예
`manifest`	`string`	예	계획은 요청 manifest, 반영은 document_id·api_id·service_id·endpoints를 갱신하고 주석·다른 항목을 보존한 manifest.
`security_impacts`	`SecurityImpact[]`	예

OpenAPI import 승인 반영#

POST /api/spec-documents/{id}/import

Workspace 잠금 뒤 계획을 다시 계산하고 승인한 변경 전체와 원문 교체를 한 트랜잭션으로 반영합니다. 승인 결과가 기존 API·Endpoint 검증을 통과하지 못하면 아무것도 저장하지 않습니다. 승인하지 않은 차이는 다음 계획에 다시 보고합니다.

인증: 세션 쿠키 또는 Agent 토큰

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예
`If-Match`	header	`string`	예	같은 본문(approved 제외)으로 받은 import-plan의 plan_token. 누락 428, 변경된 계획 412, 약한·복수·잘못된 태그 400.

요청 본문

application/json · 필수: 예

타입: ImportRequest

이름	타입	필수	설명
`content`	`string`	예	제출할 OpenAPI 원문. 반영하면 저장 원문도 이 값으로 교체합니다.
`manifest`	`string`	예	structly.yaml 원문(version 1). 인증 정보·미정의 키·중복 키·별칭은 거부합니다.
`path`	`string`	예	manifest documents의 대상 path.
`api`	`object`	아니요	최초 반영의 API 대상. 이미 연결된 문서는 생략하거나 같은 API ID만 허용합니다.
`service`	`null \| object`	아니요	제공 Service 선택. null은 명시적 미연결. 생략하면 manifest의 service_id를 쓰며, 최초 반영은 둘 중 하나가 필요합니다.
`rename`	`object`	아니요	사라진 매핑 operationId → 새 operationId. rename_candidate를 같은 Endpoint의 이름 변경으로 확정합니다.
`link`	`object`	아니요	operationId → 연결할 출처 없는 Endpoint ID. link_candidate를 확정합니다.
`recreate`	`string[]`	아니요	manifest의 Endpoint ID가 없어진 operation을 새로 만들 operationId.
`approved`	`string[]`	예	승인할 변경 ID. 빈 배열은 원문만 교체하고 Catalog 차이를 남깁니다.

응답

상태	설명
`200`	반영 결과. manifest는 갱신본이며 ETag는 새 원문을 저장한 스펙 문서의 값입니다.
`400`	400 오류.
`401`	401 오류.
`403`	403 오류.
`404`	404 오류.
`405`	405 오류.
`409`	409 오류.
`412`	412 오류.
`413`	413 오류.
`415`	415 오류.
`422`	422 오류.
`428`	428 오류.
`500`	500 오류.

200 응답 본문

타입: ImportPlan

이름	타입	필수	설명
`plan_token`	`string`	예	"import-plan:<sha256>". 대상·후보·이동 원천의 관련 revision과 요청 옵션 범위의 토큰입니다.
`applicable`	`boolean`	예	변환·식별 오류가 없으면 true. 승인 범위와 무관한 operation의 오류도 반영을 막습니다.
`api_id`	`string`	아니요
`changes`	`ImportChange[]`	예
`items`	`ImportItem[]`	예
`deletion_candidates`	`object[]`	예	원문에서 사라진 이 문서 출처 Endpoint. 삭제·출처 해제·이동은 별도로 확정합니다.
`warnings`	`SyncIssue[]`	예
`errors`	`SyncIssue[]`	예
`manifest`	`string`	예	계획은 요청 manifest, 반영은 document_id·api_id·service_id·endpoints를 갱신하고 주석·다른 항목을 보존한 manifest.
`security_impacts`	`SecurityImpact[]`	예

스펙 문서 manifest 조회#

GET /api/spec-documents/{id}/manifest

서버 기준 문서·API·제공 Service·operationId 매핑을 단일 문서 structly.yaml로 돌려줍니다. MANIFEST_MISMATCH 후 로컬 파일을 고칠 때 사용합니다. OpenAPI 문서가 아니면 422 SYNC_INVALID입니다.

인증: 세션 쿠키 또는 Agent 토큰

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예

응답

상태	설명
`200`	manifest 원문.
`400`	400 오류.
`401`	401 오류.
`403`	403 오류.
`404`	404 오류.
`405`	405 오류.
`409`	409 오류.
`422`	422 오류.
`500`	500 오류.

200 응답 본문

타입: SpecDocumentManifest

이름	타입	필수	설명
`manifest`	`string`	예	서버 기준 단일 문서 structly.yaml(version 1). 경로가 없으면 {문서 ID}.yaml입니다.

Repository 없는 OpenAPI 문서 목록#

GET /api/spec-documents

현재 Workspace의 독립 문서를 원문 없이 이름·ID 순서로 반환합니다. standalone=true가 필수입니다.

인증: 세션 쿠키 또는 Agent 토큰

Parameter

이름	위치	타입	필수	설명
`standalone`	query	`true`	예

응답

상태	설명
`200`	성공. 빈 목록은 []
`400`	INVALID_REQUEST·INVALID_ID: JSON·미정의 필드·query·조건 헤더 구문·경로 ID 오류
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`404`	REPOSITORY_NOT_FOUND·REPOSITORY_EXTERNAL_IDENTITY_NOT_FOUND·SPEC_DOCUMENT_NOT_FOUND: 현재 Organization에 기록이 없습니다.
`405`	METHOD_NOT_ALLOWED
`409`	ORGANIZATION_REQUIRED·REPOSITORY_NAME_CONFLICT·REPOSITORY_URL_CONFLICT·REPOSITORY_EXTERNAL_IDENTITY_CONFLICT·REPOSITORY_IN_USE·SPEC_DOCUMENT_NAME_CONFLICT·REGISTRATION_KEY_CONFLICT
`500`	INTERNAL_ERROR

200 응답 본문

배열(SpecDocumentSummary[])이며 표는 항목의 필드입니다.

이름	타입	필수	설명
`api_id`	`string \| null`	예
`content_format`	`string`	예	JSON으로 읽히면 json, 아니면 YAML 단일 문서로 읽어 yaml 값: `json`, `yaml`
`created_at`	`string(date-time)`	예	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.
`description`	`string`	예	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`id`	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`kind`	`string`	예	원문 최상위의 같은 이름 필드에 버전 문자열이 있어야 합니다. 값: `openapi`, `asyncapi`, `arazzo`
`name`	`string`	예
`path`	`string`	예
`repository_id`	`string \| null`	예
`spec_version`	`string`	예	원문 최상위 버전 필드 값. 서버가 저장 시 판정합니다.
`summary`	`string`	예	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`updated_at`	`string(date-time)`	예	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.

Repository 없는 OpenAPI 문서 생성#

POST /api/spec-documents

kind=openapi만 허용합니다. 같은 Workspace에서 이름은 대소문자를 무시하고 유일합니다. 같은 등록 키·입력은 200, 다른 입력은 409 REGISTRATION_KEY_CONFLICT입니다.

인증: 세션 쿠키 또는 Agent 토큰

요청 본문

application/json · 필수: 예

JSON 객체 하나. UTF-8·중복 키·미정의 필드·서버 소유 필드를 엄격히 검사하며 본문 최대 4 MiB.

타입: SpecDocumentCreate & object

이름	타입	필수	설명
`content`	`string`	예	JSON 또는 YAML 단일 문서 원문. UTF-8 1~1,048,576바이트이며 U+0000을 거부합니다. 바이트 그대로 보존합니다.
`description`	`string`	아니요	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`kind`	`string`	예	원문 최상위의 같은 이름 필드에 버전 문자열이 있어야 합니다. 값: `openapi`, `asyncapi`, `arazzo`
`name`	`string`	예	앞뒤 U+0020 공백 제거 후 1~200 유니코드 코드 포인트. 제어문자는 제거 전에 거부하며 범위는 U+0000~U+001F·U+007F~U+009F입니다. 다른 유니코드 공백·정규화는 적용하지 않습니다. 정규화 전 입력에는 maxLength 200을 적용하지 않습니다.
`path`	`string`	아니요	Repository 루트 기준 상대 경로. 앞뒤 U+0020 제거 후 0~1024자이며 제어문자·역슬래시·앞 `/`·빈·`.`·`..` segment를 거부합니다.
`expected_organization_id`	`string`	아니요	사전 확인한 Organization ID. 현재 요청 경계와 다르면 등록하지 않습니다.
`registration_key`	`string`	아니요	생성 시에만 받는 등록 재시도 키
`summary`	`string`	아니요	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.

응답

상태	설명
`200`	같은 등록 키·입력의 재시도
`201`	생성
`400`	INVALID_REQUEST·INVALID_ID: JSON·미정의 필드·query·조건 헤더 구문·경로 ID 오류
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`404`	REPOSITORY_NOT_FOUND·REPOSITORY_EXTERNAL_IDENTITY_NOT_FOUND·SPEC_DOCUMENT_NOT_FOUND: 현재 Organization에 기록이 없습니다.
`405`	METHOD_NOT_ALLOWED
`409`	ORGANIZATION_REQUIRED·REPOSITORY_NAME_CONFLICT·REPOSITORY_URL_CONFLICT·REPOSITORY_EXTERNAL_IDENTITY_CONFLICT·REPOSITORY_IN_USE·SPEC_DOCUMENT_NAME_CONFLICT·REGISTRATION_KEY_CONFLICT
`413`	PAYLOAD_TOO_LARGE: Repository 64 KiB, 스펙 문서 4 MiB 본문 상한
`415`	UNSUPPORTED_MEDIA_TYPE
`422`	VALIDATION_FAILED: 필수 값·타입·길이·문자·Git URL 문법·원문 형식 오류
`500`	INTERNAL_ERROR

200 응답 본문

타입: SpecDocument

이름	타입	필수	설명
`api_id`	`string \| null`	예
`content`	`string`	예	JSON 또는 YAML 단일 문서 원문. UTF-8 1~1,048,576바이트이며 U+0000을 거부합니다. 바이트 그대로 보존합니다.
`content_format`	`string`	예	JSON으로 읽히면 json, 아니면 YAML 단일 문서로 읽어 yaml 값: `json`, `yaml`
`created_at`	`string(date-time)`	예	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.
`description`	`string`	예	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`id`	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`kind`	`string`	예	원문 최상위의 같은 이름 필드에 버전 문자열이 있어야 합니다. 값: `openapi`, `asyncapi`, `arazzo`
`name`	`string`	예
`path`	`string`	예
`repository_id`	`string \| null`	예
`spec_version`	`string`	예	원문 최상위 버전 필드 값. 서버가 저장 시 판정합니다.
`summary`	`string`	예	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`updated_at`	`string(date-time)`	예	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.