API reference

Repository

On this page

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

Git Repository 기록.

Repository 목록#

GET /api/repositories

네 query를 모두 생략하면 name UTF-8 바이트·ID 순서의 전체 배열을 반환합니다. page·per_page가 있으면 페이지 모드입니다. 각 항목은 소속 스펙 문서 종류 요약을 함께 담습니다.

Authentication: Session cookie or Agent token

Parameters

Name	In	Type	Required	Description
`handle`	query	`string`	No	handle 정확 일치 필터. 앞뒤 공백 제거·소문자 정규화 후 비교하며 형식이 맞지 않으면 400 INVALID_REQUEST입니다. 기존 q·sort·page·per_page와 함께 사용할 수 있습니다. 결과는 최대 1건입니다.
`q`	query	`string`	No	name·summary·description의 대소문자 구분 리터럴 부분 문자열 검색. 앞뒤 공백 제거 후 200 rune 이하·제어문자 금지. 생략·빈 값은 전체 목록.
`sort`	query	`string`	No	name 오름차순·내림차순만 허용. 생략 시 기존 기본 순서(name 오름차순, ID 오름차순)를 유지합니다. Values: `name`, `-name`
`page`	query	`integer`	No	1 이상 정수. page·per_page 중 하나라도 있으면 페이지 모드로 동작합니다. 생략 시 1.
`per_page`	query	`integer`	No	1~500 정수. 생략 시 100.

Responses

Status	Description
`200`	성공. 빈 목록은 []
`400`	INVALID_REQUEST·INVALID_ID: JSON·미정의 필드·query·조건 헤더 구문·경로 ID 오류
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`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 response body

An array (RepositoryListItem[]). The table lists item fields.

Name	Type	Required	Description
`id`	`string`	Yes	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`handle`	`string`	Yes	같은 Organization의 같은 Catalog에서 고유한 Web 주소 이름. 3~39자의 영문 소문자·숫자·단일 하이픈이며 숫자로 시작할 수 있습니다.
`name`	`string`	Yes
`git_url`	`string`	Yes	수동 기록한 HTTPS·SSH URL 또는 SCP 형태 SSH 주소.
`summary`	`string`	Yes	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	Yes	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`created_at`	`string(date-time)`	Yes	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.
`updated_at`	`string(date-time)`	Yes	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.
`external_identity`	`RepositoryExternalIdentity`	Yes	같은 Organization에서 유일한 외부 키. PUT 생략은 보존, 명시적 null은 해제합니다.
`spec_document_kinds`	`string[]`	Yes	소속 스펙 문서가 있는 종류를 openapi·asyncapi·arazzo 순서로 중복 없이 담습니다. 문서가 없으면 []입니다.

Repository 생성#

POST /api/repositories

Authentication: Session cookie or Agent token

Request body

application/json · Required: Yes

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

Type: RepositoryCreate

Name	Type	Required	Description
`handle`	`string`	Yes	필수. 앞뒤 공백 제거·소문자 정규화 후 3~39자의 영문 소문자·숫자·단일 하이픈만 허용하며 정규화한 값을 저장합니다. 같은 Organization의 같은 Catalog에서 이미 사용 중이면 409 HANDLE_CONFLICT, 형식 오류는 422 VALIDATION_FAILED(오류 field handle, code invalid_format)입니다.
`name`	`string`	Yes	앞뒤 U+0020 공백 제거 후 1~200 유니코드 코드 포인트. 제어문자는 제거 전에 거부하며 범위는 U+0000~U+001F·U+007F~U+009F입니다. 다른 유니코드 공백·정규화는 적용하지 않습니다. 정규화 전 입력에는 maxLength 200을 적용하지 않습니다.
`git_url`	`string`	Yes	앞뒤 U+0020 제거 후 1~2048자. HTTPS·SSH URL 또는 SCP 형태 SSH 주소. 비밀번호·HTTPS userinfo·query·fragment는 거부합니다.
`summary`	`string`	No	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	No	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`external_identity`	`RepositoryExternalIdentity`	No	같은 Organization에서 유일한 외부 키. PUT 생략은 보존, 명시적 null은 해제합니다.

Responses

Status	Description
`201`	생성
`400`	INVALID_REQUEST·INVALID_ID: JSON·미정의 필드·query·조건 헤더 구문·경로 ID 오류
`401`	UNAUTHENTICATED
`403`	FORBIDDEN_ORIGIN·ORGANIZATION_UNVERIFIED
`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

201 response body

Type: Repository

Name	Type	Required	Description
`id`	`string`	Yes	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`handle`	`string`	Yes	같은 Organization의 같은 Catalog에서 고유한 Web 주소 이름. 3~39자의 영문 소문자·숫자·단일 하이픈이며 숫자로 시작할 수 있습니다.
`name`	`string`	Yes
`git_url`	`string`	Yes	수동 기록한 HTTPS·SSH URL 또는 SCP 형태 SSH 주소.
`summary`	`string`	Yes	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	Yes	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`created_at`	`string(date-time)`	Yes	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.
`updated_at`	`string(date-time)`	Yes	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.
`external_identity`	`RepositoryExternalIdentity`	Yes	같은 Organization에서 유일한 외부 키. PUT 생략은 보존, 명시적 null은 해제합니다.

외부 식별자로 Repository 조회#

GET /api/repositories/lookup

현재 Organization에서 외부 키로 단건 조회합니다. 이름·URL로 추정하거나 자동 생성·갱신하지 않습니다.

Authentication: Session cookie or Agent token

Parameters

Name	In	Type	Required	Description
`provider`	query	`string`	Yes	Values: `gitlab`, `github`
`instance`	query	`string`	Yes
`external_id`	query	`string`	Yes
`If-None-Match`	header	`string`	No	상세 GET의 선택 조건. 태그 목록 또는 `*`와 약한 비교로 일치하면 304, 불일치하면 200입니다.

Responses

Status	Description
`200`	연결된 Repository
`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
`422`	VALIDATION_FAILED: 필수 값·타입·길이·문자·Git URL 문법·원문 형식 오류
`500`	INTERNAL_ERROR

200 response body

Type: Repository

Name	Type	Required	Description
`id`	`string`	Yes	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`handle`	`string`	Yes	같은 Organization의 같은 Catalog에서 고유한 Web 주소 이름. 3~39자의 영문 소문자·숫자·단일 하이픈이며 숫자로 시작할 수 있습니다.
`name`	`string`	Yes
`git_url`	`string`	Yes	수동 기록한 HTTPS·SSH URL 또는 SCP 형태 SSH 주소.
`summary`	`string`	Yes	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	Yes	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`created_at`	`string(date-time)`	Yes	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.
`updated_at`	`string(date-time)`	Yes	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.
`external_identity`	`RepositoryExternalIdentity`	Yes	같은 Organization에서 유일한 외부 키. PUT 생략은 보존, 명시적 null은 해제합니다.

Repository 상세#

GET /api/repositories/{id}

Authentication: Session cookie or Agent token

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	대상 ID.
`If-None-Match`	header	`string`	No	상세 GET의 선택 조건. 태그 목록 또는 `*`와 약한 비교로 일치하면 304, 불일치하면 200입니다.

Responses

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

Type: Repository

Name	Type	Required	Description
`id`	`string`	Yes	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`handle`	`string`	Yes	같은 Organization의 같은 Catalog에서 고유한 Web 주소 이름. 3~39자의 영문 소문자·숫자·단일 하이픈이며 숫자로 시작할 수 있습니다.
`name`	`string`	Yes
`git_url`	`string`	Yes	수동 기록한 HTTPS·SSH URL 또는 SCP 형태 SSH 주소.
`summary`	`string`	Yes	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	Yes	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`created_at`	`string(date-time)`	Yes	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.
`updated_at`	`string(date-time)`	Yes	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.
`external_identity`	`RepositoryExternalIdentity`	Yes	같은 Organization에서 유일한 외부 키. PUT 생략은 보존, 명시적 null은 해제합니다.

Repository 전체 수정#

PUT /api/repositories/{id}

upsert는 없습니다. 일반 입력 검사·미존재·조건 검사 뒤 이름·URL 고유 충돌을 판정합니다.

Authentication: Session cookie or Agent token

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	대상 ID.
`If-Match`	header	`string`	Yes	상세 GET의 단일 strong ETag. 누락 428, 다른 revision·ID·리소스 412, `*`·약한·복수 태그·잘못된 구문 400. 미존재 404가 조건 평가보다 우선합니다.

Request body

application/json · Required: Yes

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

Type: RepositoryReplace

Name	Type	Required	Description
`handle`	`string`	No	선택. 생략하면 저장된 값을 유지합니다. 앞뒤 공백 제거·소문자 정규화 후 3~39자의 영문 소문자·숫자·단일 하이픈만 허용하며 정규화한 값을 저장합니다. 같은 Organization의 같은 Catalog에서 이미 사용 중이면 409 HANDLE_CONFLICT, 형식 오류는 422 VALIDATION_FAILED(오류 field handle, code invalid_format)입니다.
`name`	`string`	Yes	앞뒤 U+0020 공백 제거 후 1~200 유니코드 코드 포인트. 제어문자는 제거 전에 거부하며 범위는 U+0000~U+001F·U+007F~U+009F입니다. 다른 유니코드 공백·정규화는 적용하지 않습니다. 정규화 전 입력에는 maxLength 200을 적용하지 않습니다.
`git_url`	`string`	Yes	앞뒤 U+0020 제거 후 1~2048자. HTTPS·SSH URL 또는 SCP 형태 SSH 주소. 비밀번호·HTTPS userinfo·query·fragment는 거부합니다.
`summary`	`string`	Yes	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	Yes	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`external_identity`	`RepositoryExternalIdentity`	No	같은 Organization에서 유일한 외부 키. PUT 생략은 보존, 명시적 null은 해제합니다.

Responses

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

Type: Repository

Name	Type	Required	Description
`id`	`string`	Yes	Structly ID. Sonyflake로 발급한 정수를 고정 11자리 Base62(0-9A-Za-z)로 표현하며 대소문자를 구분합니다.
`handle`	`string`	Yes	같은 Organization의 같은 Catalog에서 고유한 Web 주소 이름. 3~39자의 영문 소문자·숫자·단일 하이픈이며 숫자로 시작할 수 있습니다.
`name`	`string`	Yes
`git_url`	`string`	Yes	수동 기록한 HTTPS·SSH URL 또는 SCP 형태 SSH 주소.
`summary`	`string`	Yes	목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다.
`description`	`string`	Yes	공백·개행을 보존하며 U+0000을 거부합니다. 빈 문자열로 설명을 비웁니다. null은 허용하지 않습니다.
`created_at`	`string(date-time)`	Yes	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.
`updated_at`	`string(date-time)`	Yes	서버가 기록한 UTC RFC 3339 시각. 저장된 마이크로초 정밀도를 보존합니다. 동시성 토큰이나 항상 증가하는 버전 번호가 아닙니다.
`external_identity`	`RepositoryExternalIdentity`	Yes	같은 Organization에서 유일한 외부 키. PUT 생략은 보존, 명시적 null은 해제합니다.

Repository 삭제#

DELETE /api/repositories/{id}

연결 Service가 있으면 조건 검사보다 먼저 409 REPOSITORY_IN_USE입니다. 소속 스펙 문서를 함께 삭제하고 그 문서를 출처로 둔 Endpoint·Workflow는 남긴 채 출처를 해제합니다.

Authentication: Session cookie or Agent token

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	대상 ID.
`If-Match`	header	`string`	Yes	상세 GET의 단일 strong ETag. 누락 428, 다른 revision·ID·리소스 412, `*`·약한·복수 태그·잘못된 구문 400. 미존재 404가 조건 평가보다 우선합니다.

Responses

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