API 레퍼런스

Endpoint

이 페이지의 내용

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

Endpoint 집합 저장·사전 검증·목록 요약과 스펙 관리 출처 해제.

API 소속 Endpoint 목록#

GET /api/apis/{api_id}/endpoints

GET /api/endpoints와 같은 REPEATABLE READ Snapshot·정렬·표현을 사용하며 api_id로 좁힙니다. q·sort·page·per_page를 선택적으로 허용합니다. 다른 query·본문은 금지합니다. GET만 지원합니다. view=summary는 부모 필드 7개만 반환하고 하위 구성·목록 ETag는 생략합니다. 생략 시 기존 전체 집합이며 다른 값·반복 키는 400입니다.

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

Parameter

이름	위치	타입	필수	설명
`api_id`	path	`string`	예
`q`	query	`string`	아니요	path·summary·description 중 하나에 대한 대소문자 구분 리터럴 부분 문자열 검색. 앞뒤 공백 제거 후 200 rune 이하·제어문자 금지. 생략·빈 값은 전체 목록.
`sort`	query	`string`	아니요	path 오름차순·내림차순만 허용. 생략 시 기존 기본 순서(Method·Path·ID 오름차순)를 유지하고, 지정하면 Method를 제외하고 Path(+ID)만 기준으로 정렬합니다. 값: `path`, `-path`
`page`	query	`integer`	아니요	1 이상 정수. page·per_page 중 하나라도 있으면 페이지 모드로 동작합니다. 생략 시 1.
`per_page`	query	`integer`	아니요	1~500 정수. 생략 시 100.
`view`	query	`string`	아니요	summary이면 하위 구성 없이 부모 필드만 반환합니다. 생략하면 전체 집합이며 반복 키·다른 값·빈 값은 400입니다. 값: `summary`

응답

상태	설명
`200`	해당 API 소속 Endpoint 객체 배열. 페이지 모드에서만 X-Pagination-* 헤더를 반환합니다.
`400`	요청 형식 오류 또는 ID 형식 오류. 입력 검증은 항목 존재 조회보다 먼저 수행합니다.
`401`	UNAUTHENTICATED: 세션·토큰이 없거나 만료·폐기되었습니다.
`403`	ORGANIZATION_UNVERIFIED: 현재 Organization 또는 Agent 토큰의 Organization이 인증 대기입니다.
`404`	ID 형식은 유효하지만 API가 없거나 다른 Organization 소속입니다.
`405`	선언된 경로에서 HEAD를 포함해 지원하지 않는 Method. Allow를 반환합니다. HEAD 오류 응답에는 HTTP 규칙에 따라 본문을 보내지 않습니다.
`409`	ORGANIZATION_REQUIRED: 세션에 현재 Organization이 없습니다.
`500`	예상하지 못한 저장·서버 오류. 내부 오류 내용은 반환하지 않습니다.

200 응답 본문

타입: Endpoint[] | EndpointSummary[]

표시할 최상위 필드가 없습니다.

Endpoint 목록#

GET /api/endpoints

같은 REPEATABLE READ Snapshot으로 집합 조회. q·sort·page·per_page를 모두 생략하면 Method·Path의 UTF-8 바이트·ID 오름차순, 소유 배열 ID순의 전체 객체 배열을 반환합니다. 다른 query·본문은 금지합니다. 항목별 ETag 없음. view=summary는 부모 필드 7개만 반환하고 하위 구성·목록 ETag는 생략합니다. 생략 시 기존 전체 집합이며 다른 값·반복 키는 400입니다.

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

Parameter

이름	위치	타입	필수	설명
`q`	query	`string`	아니요	path·summary·description 중 하나에 대한 대소문자 구분 리터럴 부분 문자열 검색. 앞뒤 공백 제거 후 200 rune 이하·제어문자 금지. 생략·빈 값은 전체 목록.
`sort`	query	`string`	아니요	path 오름차순·내림차순만 허용. 생략 시 기존 기본 순서(Method·Path·ID 오름차순)를 유지하고, 지정하면 Method를 제외하고 Path(+ID)만 기준으로 정렬합니다. 값: `path`, `-path`
`page`	query	`integer`	아니요	1 이상 정수. page·per_page 중 하나라도 있으면 페이지 모드로 동작합니다. 생략 시 1.
`per_page`	query	`integer`	아니요	1~500 정수. 생략 시 100.
`view`	query	`string`	아니요	summary이면 하위 구성 없이 부모 필드만 반환합니다. 생략하면 전체 집합이며 반복 키·다른 값·빈 값은 400입니다. 값: `summary`

응답

상태	설명
`200`	객체 배열. 페이지 모드에서만 X-Pagination-* 헤더를 반환합니다.
`400`	JSON 문법·UTF-8·유니코드·중복 키·복수 값·객체 형식·미정의 필드·query·금지 본문·조건부 갱신 헤더 오류.
`401`	UNAUTHENTICATED: 세션·토큰이 없거나 만료·폐기되었습니다.
`403`	ORGANIZATION_UNVERIFIED: 현재 Organization 또는 Agent 토큰의 Organization이 인증 대기입니다.
`409`	ORGANIZATION_REQUIRED: 세션에 현재 Organization이 없습니다.
`500`	예상하지 못한 저장·서버 오류. 내부 오류 내용은 반환하지 않습니다.

200 응답 본문

타입: Endpoint[] | EndpointSummary[]

표시할 최상위 필드가 없습니다.

Endpoint 전체 집합 생성#

POST /api/endpoints

Method·Path 필수. 서버가 모든 ID·시각 생성. POST는 자식 ID도 금지. 입력·집합 검증 후 API 참조와 FK 확인, 실패 시 전체 롤백. 본문 상한 4194304바이트. query 금지. ETag 없음.

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

Parameter

이름	위치	타입	필수	설명
`Origin`	header	`string`	아니요	세션 쿠키로 인증한 상태 변경 요청에서 필수이며 서버 origin과 같아야 합니다. Bearer 토큰 요청에는 적용하지 않습니다.

요청 본문

application/json · 필수: 예

타입: CreateEndpointRequest

이름	타입	필수	설명
`deprecated`	`boolean`	아니요	사용 중단 예정 선언. 생략은 false이며 다른 위치로 전파하지 않습니다.
`method`	`string`	예	앞뒤 U+0020 제거·ASCII 대문자 변환 후 GET·HEAD·POST·PUT·DELETE·OPTIONS·PATCH·TRACE만 허용. CONNECT 제외.
`path`	`string`	예	앞뒤 U+0020 제거 후 / 시작·1~2048자 라우트 템플릿. 상세 금지 문자·파라미터 문법은 Data Model과 HTTP 문서에서 검증. 길이 상한은 정규화 후 적용.
`summary`	`string`	아니요	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	아니요	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`api_id`	`APIIDInput`	아니요	존재하는 API ID 또는 소속 없음. 미존재·동시 삭제 API는 409 API_REFERENCE_NOT_FOUND.
`parameters`	`CreateParameter[]`	아니요
`headers`	`CreateHeader[]`	아니요
`request_body`	`CreateRequestBody \| null`	아니요
`responses`	`CreateResponse[]`	아니요
`examples`	`CreateScenario[]`	아니요
`external_references`	`ExternalReference[]`	아니요	생략하면 빈 배열로 저장합니다.
`security`	`object[] \| null`	아니요	null은 선언 부재 또는 Endpoint의 API 상속입니다. 배열 항목은 OR, 항목 안의 방식은 AND이며 빈 객체는 익명 대안입니다.

응답

상태	설명
`201`	생성한 전체 객체.
`400`	JSON 문법·UTF-8·유니코드·중복 키·복수 값·객체 형식·미정의 필드·query·금지 본문·조건부 갱신 헤더 오류.
`401`	UNAUTHENTICATED: 세션·토큰이 없거나 만료·폐기되었습니다.
`403`	Origin 검사 실패 또는 인증 대기 Organization 사용 거부입니다.
`409`	소속 API가 없거나 동시 삭제되어 전체 저장을 거부합니다. 또는 ORGANIZATION_REQUIRED: 세션에 현재 Organization이 없습니다.
`413`	전체 수신 POST·PUT 본문이 4 MiB(4194304바이트)를 초과함. 개별 Schema 제한은 422로 구분.
`415`	Content-Type 누락·지원하지 않는 Media Type·지원하지 않는 Content-Encoding. UTF-8 application/json만 지원하고 파라미터는 charset=utf-8만 허용합니다. Content-Encoding을 생략한 비압축 JSON은 허용하며 압축 본문은 지원하지 않습니다.
`422`	필드·Schema·예제·집합·자식 소유권 검증 실패. 부모·자식·시각·revision 전체 유지.
`500`	예상하지 못한 저장·서버 오류. 내부 오류 내용은 반환하지 않습니다.

201 응답 본문

타입: Endpoint

이름	타입	필수	설명
`deprecated`	`boolean`	예	사용 중단 예정 선언. 생략은 false이며 다른 위치로 전파하지 않습니다.
`id`	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`created_at`	`string(date-time)`	예	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.
`updated_at`	`string(date-time)`	예	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.
`method`	`string`	예	값: `GET`, `HEAD`, `POST`, `PUT`, `DELETE`, `OPTIONS`, `PATCH`, `TRACE`
`path`	`string`	예	정규화된 Path. 디코딩·대소문자·슬래시 변환 없음.
`summary`	`string`	예	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	예	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`api_id`	`APIID`	예
`parameters`	`Parameter[]`	예
`headers`	`Header[]`	예
`request_body`	`RequestBody \| null`	예
`responses`	`Response[]`	예
`examples`	`Scenario[]`	예
`external_references`	`ExternalReference[]`	예	코드·외부 문서 출처 목록입니다. 입력 순서를 보존합니다.
`source`	`null \| object`	예
`security`	`object[] \| null`	예	null은 선언 부재 또는 Endpoint의 API 상속입니다. 배열 항목은 OR, 항목 안의 방식은 AND이며 빈 객체는 익명 대안입니다.

Endpoint 집합 상세 조회#

GET /api/endpoints/{id}

하나의 Snapshot으로 부모·자식·revision 조회. 소유 행 ID순·고정 JSON 직렬화로 같은 토큰의 표현 바이트 유지. query·본문 금지. If-None-Match는 약한 비교로 일치 304·불일치 200, 미존재 404 우선.

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

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예	Endpoint ID. 잘못된 형식은 400 INVALID_ID.
`If-None-Match`	header	`string`	아니요	상세 GET의 선택 조건. 강한·약한 태그, 태그 목록 또는 를 허용하며 약한 비교로 일치하면 304, 불일치하면 200. 와 태그 혼합 또는 잘못된 형식은 400. 항목 미존재 404는 조건 평가에 우선합니다.

응답

상태	설명
`200`	전체 집합과 강한 ETag.
`304`	If-None-Match 일치. 본문·Content-Type 없음.
`400`	요청 형식 오류 또는 ID 형식 오류. 입력 검증은 항목 존재 조회보다 먼저 수행합니다.
`401`	UNAUTHENTICATED: 세션·토큰이 없거나 만료·폐기되었습니다.
`403`	ORGANIZATION_UNVERIFIED: 현재 Organization 또는 Agent 토큰의 Organization이 인증 대기입니다.
`404`	유효한 ID의 Endpoint가 없거나 삭제됨. If-Match 누락·불일치보다 우선.
`409`	ORGANIZATION_REQUIRED: 세션에 현재 Organization이 없습니다.
`500`	예상하지 못한 저장·서버 오류. 내부 오류 내용은 반환하지 않습니다.

200 응답 본문

타입: Endpoint

이름	타입	필수	설명
`deprecated`	`boolean`	예	사용 중단 예정 선언. 생략은 false이며 다른 위치로 전파하지 않습니다.
`id`	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`created_at`	`string(date-time)`	예	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.
`updated_at`	`string(date-time)`	예	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.
`method`	`string`	예	값: `GET`, `HEAD`, `POST`, `PUT`, `DELETE`, `OPTIONS`, `PATCH`, `TRACE`
`path`	`string`	예	정규화된 Path. 디코딩·대소문자·슬래시 변환 없음.
`summary`	`string`	예	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	예	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`api_id`	`APIID`	예
`parameters`	`Parameter[]`	예
`headers`	`Header[]`	예
`request_body`	`RequestBody \| null`	예
`responses`	`Response[]`	예
`examples`	`Scenario[]`	예
`external_references`	`ExternalReference[]`	예	코드·외부 문서 출처 목록입니다. 입력 순서를 보존합니다.
`source`	`null \| object`	예
`security`	`object[] \| null`	예	null은 선언 부재 또는 Endpoint의 API 상속입니다. 배열 항목은 OR, 항목 안의 방식은 AND이며 빈 객체는 익명 대안입니다.

Endpoint 전체 집합 교체#

PUT /api/endpoints/{id}

최상위 입력 9개 필수, 자식 누락은 삭제·ID 생략만 신규. 입력 검증 후 부모 잠금·404·If-Match 428/412·자식 소유권 422·소속 API 409·집합 쓰기 순서. If-Unmodified-Since는 If-Match가 있으면 무시, 날짜 조건만으로 대체 불가. no-op도 부모 revision 증가. query 금지. 본문 상한 4194304바이트. 성공 ETag 없음.

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

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예	Endpoint ID. 잘못된 형식은 400 INVALID_ID.
`If-Match`	header	`string`	예	상세 GET의 단일 강한 ETag. *·약한·복수 태그는 400. 입력 검증·행 잠금 후 없는 Endpoint는 404, 그 외 누락 428·불일치 412. 자식 소유권·API 참조 존재 검사는 조건 평가 뒤. If-Match가 있으면 If-Unmodified-Since는 무시.
`Origin`	header	`string`	아니요	세션 쿠키로 인증한 상태 변경 요청에서 필수이며 서버 origin과 같아야 합니다. Bearer 토큰 요청에는 적용하지 않습니다.

요청 본문

application/json · 필수: 예

타입: ReplaceEndpointRequest

이름	타입	필수	설명
`deprecated`	`boolean`	아니요	사용 중단 예정 선언. 생략은 false이며 다른 위치로 전파하지 않습니다.
`method`	`string`	예	앞뒤 U+0020 제거·ASCII 대문자 변환 후 GET·HEAD·POST·PUT·DELETE·OPTIONS·PATCH·TRACE만 허용. CONNECT 제외.
`path`	`string`	예	앞뒤 U+0020 제거 후 / 시작·1~2048자 라우트 템플릿. 상세 금지 문자·파라미터 문법은 Data Model과 HTTP 문서에서 검증. 길이 상한은 정규화 후 적용.
`summary`	`string`	예	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	예	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`api_id`	`APIIDInput`	예	존재하는 API ID 또는 소속 없음. 미존재·동시 삭제 API는 409 API_REFERENCE_NOT_FOUND.
`parameters`	`ReplaceParameter[]`	예
`headers`	`ReplaceHeader[]`	예
`request_body`	`ReplaceRequestBody \| null`	예
`responses`	`ReplaceResponse[]`	예
`examples`	`ReplaceScenario[]`	예
`external_references`	`ExternalReference[]`	아니요	생략하면 저장된 값을 보존하고 []는 전체 해제입니다.
`security`	`object[] \| null`	아니요	null은 선언 부재 또는 Endpoint의 API 상속입니다. 배열 항목은 OR, 항목 안의 방식은 AND이며 빈 객체는 익명 대안입니다.

응답

상태	설명
`200`	저장한 전체 집합. 정규화가 있으므로 ETag 없음.
`400`	요청 형식 오류 또는 ID 형식 오류. 입력 검증은 항목 존재 조회보다 먼저 수행합니다.
`401`	UNAUTHENTICATED: 세션·토큰이 없거나 만료·폐기되었습니다.
`403`	Origin 검사 실패 또는 인증 대기 Organization 사용 거부입니다.
`404`	유효한 ID의 Endpoint가 없거나 삭제됨. If-Match 누락·불일치보다 우선.
`409`	소속 API가 없거나 동시 삭제되어 전체 저장을 거부합니다. 또는 ORGANIZATION_REQUIRED: 세션에 현재 Organization이 없습니다.
`412`	부모 행 잠금 후 전체 Endpoint 집합의 현재 ETag와 불일치. 자식 소유권·소속 API 존재 검사보다 우선. 값·시각·revision 모두 유지.
`413`	전체 수신 POST·PUT 본문이 4 MiB(4194304바이트)를 초과함. 개별 Schema 제한은 422로 구분.
`415`	Content-Type 누락·지원하지 않는 Media Type·지원하지 않는 Content-Encoding. UTF-8 application/json만 지원하고 파라미터는 charset=utf-8만 허용합니다. Content-Encoding을 생략한 비압축 JSON은 허용하며 압축 본문은 지원하지 않습니다.
`422`	필드·Schema·예제·집합·자식 소유권 검증 실패. 부모·자식·시각·revision 전체 유지.
`428`	입력 검증·항목 존재 확인 후 If-Match 누락. 날짜 조건으로 대체 불가.
`500`	예상하지 못한 저장·서버 오류. 내부 오류 내용은 반환하지 않습니다.

200 응답 본문

타입: Endpoint

이름	타입	필수	설명
`deprecated`	`boolean`	예	사용 중단 예정 선언. 생략은 false이며 다른 위치로 전파하지 않습니다.
`id`	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`created_at`	`string(date-time)`	예	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.
`updated_at`	`string(date-time)`	예	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.
`method`	`string`	예	값: `GET`, `HEAD`, `POST`, `PUT`, `DELETE`, `OPTIONS`, `PATCH`, `TRACE`
`path`	`string`	예	정규화된 Path. 디코딩·대소문자·슬래시 변환 없음.
`summary`	`string`	예	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	예	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`api_id`	`APIID`	예
`parameters`	`Parameter[]`	예
`headers`	`Header[]`	예
`request_body`	`RequestBody \| null`	예
`responses`	`Response[]`	예
`examples`	`Scenario[]`	예
`external_references`	`ExternalReference[]`	예	코드·외부 문서 출처 목록입니다. 입력 순서를 보존합니다.
`source`	`null \| object`	예
`security`	`object[] \| null`	예	null은 선언 부재 또는 Endpoint의 API 상속입니다. 배열 항목은 OR, 항목 안의 방식은 AND이며 빈 객체는 익명 대안입니다.

Endpoint 집합 물리 삭제#

DELETE /api/endpoints/{id}

query·본문 금지. 부모 잠금 후 없는 항목 404, If-Match 누락 428·불일치 412. If-Unmodified-Since는 If-Match가 있으면 무시, 날짜 조건 대체 불가. 소유 행·예제 CASCADE, API 유지.

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

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예	Endpoint ID. 잘못된 형식은 400 INVALID_ID.
`If-Match`	header	`string`	예	상세 GET의 단일 강한 ETag. *·약한·복수 태그는 400. 입력 검증·행 잠금 후 없는 Endpoint는 404, 그 외 누락 428·불일치 412. 자식 소유권·API 참조 존재 검사는 조건 평가 뒤. If-Match가 있으면 If-Unmodified-Since는 무시.
`Origin`	header	`string`	아니요	세션 쿠키로 인증한 상태 변경 요청에서 필수이며 서버 origin과 같아야 합니다. Bearer 토큰 요청에는 적용하지 않습니다.

응답

상태	설명
`204`	Endpoint와 소유 행 삭제. 본문·Content-Type 없음.
`400`	요청 형식 오류 또는 ID 형식 오류. 입력 검증은 항목 존재 조회보다 먼저 수행합니다.
`401`	UNAUTHENTICATED: 세션·토큰이 없거나 만료·폐기되었습니다.
`403`	Origin 검사 실패 또는 인증 대기 Organization 사용 거부입니다.
`404`	유효한 ID의 Endpoint가 없거나 삭제됨. If-Match 누락·불일치보다 우선.
`409`	ENDPOINT_IN_USE: Workflow가 참조하는 Endpoint는 If-Match 누락·불일치보다 먼저 삭제를 거부합니다.
`412`	부모 행 잠금 후 전체 Endpoint 집합의 현재 ETag와 불일치. 자식 소유권·소속 API 존재 검사보다 우선. 값·시각·revision 모두 유지.
`428`	입력 검증·항목 존재 확인 후 If-Match 누락. 날짜 조건으로 대체 불가.
`500`	예상하지 못한 저장·서버 오류. 내부 오류 내용은 반환하지 않습니다.

Endpoint 생성 후보 사전 검증(저장 없음)#

POST /api/endpoints/validate

POST /api/endpoints와 같은 요청 본문·크기·Schema 검증·소속 API 참조 검사를 저장 없이 실행합니다. 성공은 valid:true·operation:create이며 실패는 생성과 같은 상태·오류를 반환합니다. 검증 성공은 조회 시점의 유효성만 뜻하며 저장 성공을 보장하지 않습니다.

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

Parameter

이름	위치	타입	필수	설명
`Origin`	header	`string`	아니요	세션 쿠키로 인증한 상태 변경 요청에서 필수이며 서버 origin과 같아야 합니다. Bearer 토큰 요청에는 적용하지 않습니다.

요청 본문

application/json · 필수: 예

타입: CreateEndpointRequest

이름	타입	필수	설명
`deprecated`	`boolean`	아니요	사용 중단 예정 선언. 생략은 false이며 다른 위치로 전파하지 않습니다.
`method`	`string`	예	앞뒤 U+0020 제거·ASCII 대문자 변환 후 GET·HEAD·POST·PUT·DELETE·OPTIONS·PATCH·TRACE만 허용. CONNECT 제외.
`path`	`string`	예	앞뒤 U+0020 제거 후 / 시작·1~2048자 라우트 템플릿. 상세 금지 문자·파라미터 문법은 Data Model과 HTTP 문서에서 검증. 길이 상한은 정규화 후 적용.
`summary`	`string`	아니요	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	아니요	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`api_id`	`APIIDInput`	아니요	존재하는 API ID 또는 소속 없음. 미존재·동시 삭제 API는 409 API_REFERENCE_NOT_FOUND.
`parameters`	`CreateParameter[]`	아니요
`headers`	`CreateHeader[]`	아니요
`request_body`	`CreateRequestBody \| null`	아니요
`responses`	`CreateResponse[]`	아니요
`examples`	`CreateScenario[]`	아니요
`external_references`	`ExternalReference[]`	아니요	생략하면 빈 배열로 저장합니다.
`security`	`object[] \| null`	아니요	null은 선언 부재 또는 Endpoint의 API 상속입니다. 배열 항목은 OR, 항목 안의 방식은 AND이며 빈 객체는 익명 대안입니다.

응답

상태	설명
`200`	검증 성공. 저장하지 않으며 ETag·Location도 없습니다.
`400`	JSON 문법·UTF-8·유니코드·중복 키·복수 값·객체 형식·미정의 필드·query·금지 본문·조건부 갱신 헤더 오류.
`401`	UNAUTHENTICATED: 세션·토큰이 없거나 만료·폐기되었습니다.
`403`	Origin 검사 실패 또는 인증 대기 Organization 사용 거부입니다.
`409`	소속 API가 없거나 동시 삭제되어 전체 저장을 거부합니다. 또는 ORGANIZATION_REQUIRED: 세션에 현재 Organization이 없습니다.
`413`	전체 수신 POST·PUT 본문이 4 MiB(4194304바이트)를 초과함. 개별 Schema 제한은 422로 구분.
`415`	Content-Type 누락·지원하지 않는 Media Type·지원하지 않는 Content-Encoding. UTF-8 application/json만 지원하고 파라미터는 charset=utf-8만 허용합니다. Content-Encoding을 생략한 비압축 JSON은 허용하며 압축 본문은 지원하지 않습니다.
`422`	필드·Schema·예제·집합·자식 소유권 검증 실패. 부모·자식·시각·revision 전체 유지.
`500`	예상하지 못한 저장·서버 오류. 내부 오류 내용은 반환하지 않습니다.

200 응답 본문

타입: ValidationResult

이름	타입	필수	설명
`valid`	`true`	예
`operation`	`string`	예	값: `create`, `update`

Endpoint 수정 후보 사전 검증(저장 없음)#

PUT /api/endpoints/{id}/validate

PUT /api/endpoints/{id}와 같은 요청 본문·If-Match·참조 검사를 저장 없이 실행합니다. 성공은 valid:true·operation:update이며 실패는 전체 수정과 같은 상태·오류를 반환합니다. 검증 성공은 조회 시점의 유효성만 뜻하며 저장 성공을 보장하지 않습니다.

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

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예	Endpoint ID. 잘못된 형식은 400 INVALID_ID.
`If-Match`	header	`string`	예	상세 GET의 단일 강한 ETag. *·약한·복수 태그는 400. 입력 검증·행 잠금 후 없는 Endpoint는 404, 그 외 누락 428·불일치 412. 자식 소유권·API 참조 존재 검사는 조건 평가 뒤. If-Match가 있으면 If-Unmodified-Since는 무시.
`Origin`	header	`string`	아니요	세션 쿠키로 인증한 상태 변경 요청에서 필수이며 서버 origin과 같아야 합니다. Bearer 토큰 요청에는 적용하지 않습니다.

요청 본문

application/json · 필수: 예

타입: ReplaceEndpointRequest

이름	타입	필수	설명
`deprecated`	`boolean`	아니요	사용 중단 예정 선언. 생략은 false이며 다른 위치로 전파하지 않습니다.
`method`	`string`	예	앞뒤 U+0020 제거·ASCII 대문자 변환 후 GET·HEAD·POST·PUT·DELETE·OPTIONS·PATCH·TRACE만 허용. CONNECT 제외.
`path`	`string`	예	앞뒤 U+0020 제거 후 / 시작·1~2048자 라우트 템플릿. 상세 금지 문자·파라미터 문법은 Data Model과 HTTP 문서에서 검증. 길이 상한은 정규화 후 적용.
`summary`	`string`	예	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	예	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`api_id`	`APIIDInput`	예	존재하는 API ID 또는 소속 없음. 미존재·동시 삭제 API는 409 API_REFERENCE_NOT_FOUND.
`parameters`	`ReplaceParameter[]`	예
`headers`	`ReplaceHeader[]`	예
`request_body`	`ReplaceRequestBody \| null`	예
`responses`	`ReplaceResponse[]`	예
`examples`	`ReplaceScenario[]`	예
`external_references`	`ExternalReference[]`	아니요	생략하면 저장된 값을 보존하고 []는 전체 해제입니다.
`security`	`object[] \| null`	아니요	null은 선언 부재 또는 Endpoint의 API 상속입니다. 배열 항목은 OR, 항목 안의 방식은 AND이며 빈 객체는 익명 대안입니다.

응답

상태	설명
`200`	검증 성공. 저장하지 않으며 ETag도 없습니다.
`400`	요청 형식 오류 또는 ID 형식 오류. 입력 검증은 항목 존재 조회보다 먼저 수행합니다.
`401`	UNAUTHENTICATED: 세션·토큰이 없거나 만료·폐기되었습니다.
`403`	Origin 검사 실패 또는 인증 대기 Organization 사용 거부입니다.
`404`	유효한 ID의 Endpoint가 없거나 삭제됨. If-Match 누락·불일치보다 우선.
`409`	소속 API가 없거나 동시 삭제되어 전체 저장을 거부합니다. 또는 ORGANIZATION_REQUIRED: 세션에 현재 Organization이 없습니다.
`412`	부모 행 잠금 후 전체 Endpoint 집합의 현재 ETag와 불일치. 자식 소유권·소속 API 존재 검사보다 우선. 값·시각·revision 모두 유지.
`413`	전체 수신 POST·PUT 본문이 4 MiB(4194304바이트)를 초과함. 개별 Schema 제한은 422로 구분.
`415`	Content-Type 누락·지원하지 않는 Media Type·지원하지 않는 Content-Encoding. UTF-8 application/json만 지원하고 파라미터는 charset=utf-8만 허용합니다. Content-Encoding을 생략한 비압축 JSON은 허용하며 압축 본문은 지원하지 않습니다.
`422`	필드·Schema·예제·집합·자식 소유권 검증 실패. 부모·자식·시각·revision 전체 유지.
`428`	입력 검증·항목 존재 확인 후 If-Match 누락. 날짜 조건으로 대체 불가.
`500`	예상하지 못한 저장·서버 오류. 내부 오류 내용은 반환하지 않습니다.

200 응답 본문

타입: ValidationResult

이름	타입	필수	설명
`valid`	`true`	예
`operation`	`string`	예	값: `create`, `update`

Endpoint 스펙 출처 해제#

POST /api/endpoints/{id}/release-source

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

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예
`If-Match`	header	`string`	예	상세 GET의 단일 강한 ETag. *·약한·복수 태그는 400. 입력 검증·행 잠금 후 없는 Endpoint는 404, 그 외 누락 428·불일치 412. 자식 소유권·API 참조 존재 검사는 조건 평가 뒤. If-Match가 있으면 If-Unmodified-Since는 무시.

응답

상태	설명
`200`	출처를 해제한 Endpoint
`400`	400 오류. SYNC_INVALID의 data에는 변환 오류 code와 JSON Pointer를 포함합니다.
`401`	401 오류. SYNC_INVALID의 data에는 변환 오류 code와 JSON Pointer를 포함합니다.
`403`	403 오류. SYNC_INVALID의 data에는 변환 오류 code와 JSON Pointer를 포함합니다.
`404`	404 오류. SYNC_INVALID의 data에는 변환 오류 code와 JSON Pointer를 포함합니다.
`405`	405 오류. SYNC_INVALID의 data에는 변환 오류 code와 JSON Pointer를 포함합니다.
`409`	409 오류. SYNC_INVALID의 data에는 변환 오류 code와 JSON Pointer를 포함합니다.
`412`	412 오류. SYNC_INVALID의 data에는 변환 오류 code와 JSON Pointer를 포함합니다.
`428`	428 오류. SYNC_INVALID의 data에는 변환 오류 code와 JSON Pointer를 포함합니다.
`500`	500 오류. SYNC_INVALID의 data에는 변환 오류 code와 JSON Pointer를 포함합니다.

200 응답 본문

타입: Endpoint

이름	타입	필수	설명
`deprecated`	`boolean`	예	사용 중단 예정 선언. 생략은 false이며 다른 위치로 전파하지 않습니다.
`id`	`string`	예	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`created_at`	`string(date-time)`	예	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.
`updated_at`	`string(date-time)`	예	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.
`method`	`string`	예	값: `GET`, `HEAD`, `POST`, `PUT`, `DELETE`, `OPTIONS`, `PATCH`, `TRACE`
`path`	`string`	예	정규화된 Path. 디코딩·대소문자·슬래시 변환 없음.
`summary`	`string`	예	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	예	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`api_id`	`APIID`	예
`parameters`	`Parameter[]`	예
`headers`	`Header[]`	예
`request_body`	`RequestBody \| null`	예
`responses`	`Response[]`	예
`examples`	`Scenario[]`	예
`external_references`	`ExternalReference[]`	예	코드·외부 문서 출처 목록입니다. 입력 순서를 보존합니다.
`source`	`null \| object`	예
`security`	`object[] \| null`	예	null은 선언 부재 또는 Endpoint의 API 상속입니다. 배열 항목은 OR, 항목 안의 방식은 AND이며 빈 객체는 익명 대안입니다.

Endpoint 적용 인증 조회#

GET /api/endpoints/{id}/security

Endpoint·API 선언을 같은 Snapshot에서 읽습니다. 조회 ETag는 두 자산의 상태를 포함하며 Endpoint 수정 토큰으로 쓰지 않습니다.

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

Parameter

이름	위치	타입	필수	설명
`id`	path	`string`	예	Endpoint ID. 잘못된 형식은 400 INVALID_ID.
`If-None-Match`	header	`string`	아니요	상세 GET의 선택 조건. 강한·약한 태그, 태그 목록 또는 를 허용하며 약한 비교로 일치하면 304, 불일치하면 200. 와 태그 혼합 또는 잘못된 형식은 400. 항목 미존재 404는 조건 평가에 우선합니다.

응답

상태	설명
`200`	전체 집합과 강한 ETag.
`304`	If-None-Match 일치. 본문·Content-Type 없음.
`400`	요청 형식 오류 또는 ID 형식 오류. 입력 검증은 항목 존재 조회보다 먼저 수행합니다.
`401`	UNAUTHENTICATED: 세션·토큰이 없거나 만료·폐기되었습니다.
`403`	ORGANIZATION_UNVERIFIED: 현재 Organization 또는 Agent 토큰의 Organization이 인증 대기입니다.
`404`	유효한 ID의 Endpoint가 없거나 삭제됨. If-Match 누락·불일치보다 우선.
`409`	ORGANIZATION_REQUIRED: 세션에 현재 Organization이 없습니다.
`500`	예상하지 못한 저장·서버 오류. 내부 오류 내용은 반환하지 않습니다.

200 응답 본문

타입: EffectiveSecurity

이름	타입	필수	설명
`endpoint_id`	`string`	예
`api_id`	`string \| null`	예
`origin`	`string`	예	값: `api`, `endpoint`, `none`
`state`	`string`	예	값: `undeclared`, `no_requirements`, `anonymous_allowed`, `required`
`requirements`	`object[] \| null`	예	null은 선언 부재 또는 Endpoint의 API 상속입니다. 배열 항목은 OR, 항목 안의 방식은 AND이며 빈 객체는 익명 대안입니다.
`schemes`	`object`	예