API reference

Endpoint

On this page

This page is generated from the public contract. Descriptions are shown in the original Korean.

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입니다.

Authentication: Session cookie or Agent token

Parameters

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

Responses

Status	Description
`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 response body

Type: Endpoint[] | EndpointSummary[]

No top-level fields to show.

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입니다.

Authentication: Session cookie or Agent token

Parameters

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

Responses

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

200 response body

Type: Endpoint[] | EndpointSummary[]

No top-level fields to show.

Endpoint 전체 집합 생성#

POST /api/endpoints

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

Authentication: Session cookie or Agent token

Parameters

Name	In	Type	Required	Description
`Origin`	header	`string`	No	세션 쿠키로 인증한 상태 변경 요청에서 필수이며 서버 origin과 같아야 합니다. Bearer 토큰 요청에는 적용하지 않습니다.

Request body

application/json · Required: Yes

Type: CreateEndpointRequest

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

Responses

Status	Description
`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 response body

Type: Endpoint

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

Endpoint 집합 상세 조회#

GET /api/endpoints/{id}

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

Authentication: Session cookie or Agent token

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Endpoint ID. 잘못된 형식은 400 INVALID_ID.
`If-None-Match`	header	`string`	No	상세 GET의 선택 조건. 강한·약한 태그, 태그 목록 또는 를 허용하며 약한 비교로 일치하면 304, 불일치하면 200. 와 태그 혼합 또는 잘못된 형식은 400. 항목 미존재 404는 조건 평가에 우선합니다.

Responses

Status	Description
`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 response body

Type: Endpoint

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

Authentication: Session cookie or Agent token

Parameters

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

Request body

application/json · Required: Yes

Type: ReplaceEndpointRequest

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

Responses

Status	Description
`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 response body

Type: Endpoint

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

Endpoint 집합 물리 삭제#

DELETE /api/endpoints/{id}

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

Authentication: Session cookie or Agent token

Parameters

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

Responses

Status	Description
`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이며 실패는 생성과 같은 상태·오류를 반환합니다. 검증 성공은 조회 시점의 유효성만 뜻하며 저장 성공을 보장하지 않습니다.

Authentication: Session cookie or Agent token

Parameters

Name	In	Type	Required	Description
`Origin`	header	`string`	No	세션 쿠키로 인증한 상태 변경 요청에서 필수이며 서버 origin과 같아야 합니다. Bearer 토큰 요청에는 적용하지 않습니다.

Request body

application/json · Required: Yes

Type: CreateEndpointRequest

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

Responses

Status	Description
`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 response body

Type: ValidationResult

Name	Type	Required	Description
`valid`	`true`	Yes
`operation`	`string`	Yes	Values: `create`, `update`

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

PUT /api/endpoints/{id}/validate

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

Authentication: Session cookie or Agent token

Parameters

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

Request body

application/json · Required: Yes

Type: ReplaceEndpointRequest

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

Responses

Status	Description
`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 response body

Type: ValidationResult

Name	Type	Required	Description
`valid`	`true`	Yes
`operation`	`string`	Yes	Values: `create`, `update`

Endpoint 스펙 출처 해제#

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

Authentication: Session cookie or Agent token

Parameters

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

Responses

Status	Description
`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 response body

Type: Endpoint

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

Endpoint 적용 인증 조회#

GET /api/endpoints/{id}/security

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

Authentication: Session cookie or Agent token

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Endpoint ID. 잘못된 형식은 400 INVALID_ID.
`If-None-Match`	header	`string`	No	상세 GET의 선택 조건. 강한·약한 태그, 태그 목록 또는 를 허용하며 약한 비교로 일치하면 304, 불일치하면 200. 와 태그 혼합 또는 잘못된 형식은 400. 항목 미존재 404는 조건 평가에 우선합니다.

Responses

Status	Description
`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 response body

Type: EffectiveSecurity

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