이 페이지에서

차트 주석 API

지역

기본 URL은 프로젝트의 데이터 상주 위치에 따라 달라집니다. 이 페이지의 모든 예제에서 프로젝트가 Amplitude의 EU 데이터 센터를 사용하지 않는 한 기본 URL을 사용하십시오. 이 경우 이 표의 EU 기본 URL을 사용하십시오.

요청은 https://amplitude.com(기본값) 또는 https://analytics.eu.amplitude.com (EU)로 이동합니다. https://analytics.amplitude.com호스트 이름은 분석 웹 앱(브라우저 UI)입니다. REST 요청에는 analytics.amplitude.com이 표에 나와 있는 호스트를 사용하십시오.

데이터 상주기본 URL
기본값https://amplitude.com
EUhttps://analytics.eu.amplitude.com

주석 범주

주석 범주를 관리하여 주석을 구성합니다. 범주를 생성하고 해당 이름을 업데이트한 다음 주석에 할당합니다.

주석 범주 작성

curl --location --request POST 'https://amplitude.com/api/3/annotation-categories' \
--header 'Authorization: Basic {api-key}:{secret-key}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "category": "Releases"
}'

바디 매개변수

매개 변수설명
category필수입니다. 문자열입니다. 범주의 이름입니다.

응답

json
{
  "data": {
    "id": 6789,
    "name": "Releases"
  }
}

오류 응답

  • 400 - 잘못된 필드
  • 409 - 범주가 이미 존재합니다

모든 주석 범주 가져오기

curl --location --request GET 'https://amplitude.com/api/3/annotation-categories' \
-u '{api-key}:{secret-key}'

쿼리 매개 변수

매개 변수설명
category선택 사항입니다. 문자열입니다. 지정된 경우 지정된 범주만 반환합니다. 그렇지 않으면 모든 범주를 반환합니다.

응답

json
{
  "data": [
    {
      "id": 12345,
      "name": "Alerts"
    },
    {
      "id": 6789,
      "name": "Releases"
    }
  ]
}

오류 응답

  • 400 - 잘못된 범주
  • 404 - 범주를 찾을 수 없습니다.

ID별로 주석 범주 가져오기

curl --location --request GET 'https://amplitude.com/api/3/annotation-categories/:category_id' \
-u '{api-key}:{secret-key}'

경로 매개변수

매개 변수설명
category_id필수입니다. 정수입니다. 범주의 ID입니다.

응답

json
{
  "data": {
    "id": 12345,
    "name": "Alerts"
  }
}

오류 응답

  • 400 - 잘못된 범주 ID
  • 404 - 범주를 찾을 수 없습니다.

주석 범주 업데이트

curl --location --request PUT 'https://amplitude.com/api/3/annotation-categories/:category_id' \
--header 'Authorization: Basic {api-key}:{secret-key}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "category": "Updated Category Name"
}'

경로 매개변수

매개 변수설명
category_id필수입니다. 정수입니다. 업데이트할 범주의 ID입니다.

바디 매개변수

매개 변수설명
category필수입니다. 문자열입니다. 범주의 새 이름입니다.

응답

json
{
  "data": {
    "id": 569,
    "category": "Updated category name"
  }
}

오류 응답

  • 400 - 잘못된 범주 ID
  • 404 - 범주를 찾을 수 없습니다.
  • 409 - 범주가 이미 존재합니다

주석 범주 삭제

curl --location --request DELETE 'https://amplitude.com/api/3/annotation-categories/:category_id' \
-u '{api-key}:{secret-key}'

경로 매개변수

매개 변수설명
category_id필수입니다. 정수입니다. 삭제할 범주의 ID입니다.

응답

json
{
  "success": true
}

오류 응답

  • 400 - 잘못된 범주 ID
  • 404 - 범주를 찾을 수 없습니다.

주석 범주 대량 업데이트

한 범주를 여러 주석에 한 번에 지정합니다.

curl --location --request PUT 'https://amplitude.com/api/3/annotation-categories/bulk/:category_id' \
--header 'Authorization: Basic {api-key}:{secret-key}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "annotation_ids": [12345, 67890, 11111]
}'

경로 매개변수

매개 변수설명
category_id필수입니다. 정수입니다. 할당할 범주의 ID입니다.

바디 매개변수

매개 변수설명
annotation_ids필수입니다. 배열. 업데이트할 주석 ID 목록입니다.

응답

json
{
    "data": [
        {
            "id": 12345,
            "start": "2025-12-18T15:00:00+00:00",
            "label": "test",
            "details": null,
            "category": {
                "id": 12345,
                "category": "Alerts"
            },
            "end": null,
            "chart_id": null
        },
        …
    ]
}

오류 응답

  • 400 - 잘못된 범주 ID
  • 400 - 잘못된 주석 ID
  • 400 - 하나 이상의 잘못된 주석 ID
  • 404 - 범주를 찾을 수 없습니다.

주석

차트 주석을 생성, 검색, 업데이트 및 삭제할 수 있습니다. 주석은 시간별로 세분화되어 단일 날짜 또는 시간 범위에 걸쳐 제공될 수 있습니다.

주석 작성

curl --location --request POST 'https://amplitude.com/api/3/annotations' \
--header 'Authorization: Basic {api-key}:{secret-key}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "label": "Feature X Release",
  "start": "2025-11-01T07:00:00+00:00",
  "category": "Releases",
  "chart_id": "abc123",
  "details": "This marks the release of feature X",
  "end": "2025-11-10T07:00:00+01:00"
}'

바디 매개변수

매개 변수설명
label필수입니다. 문자열입니다. 주석의 제목입니다.
start필수입니다. 문자열입니다. 이 주석의 시작에 해당하는 타임스탬프는 ISO 8601 형식(YYYY-MM-DDThh:mmTZD)입니다. 예를 들어: "2025-11-01T07:00:00+00:00".
category선택 사항입니다. 문자열입니다. 주석이 속한 범주의 이름입니다.
chart_id선택 사항입니다. 문자열입니다. 주석을 달 차트의 ID(URL에서 찾을 수 있음)입니다. chart_id을(를) 포함하지 않을 경우 주석은 전역적이며 프로젝트의 모든 차트에 나타납니다.
details선택 사항입니다. 문자열입니다. 주석에 대한 세부 정보입니다.
end선택 사항입니다. 문자열입니다. ISO 8601 형식으로 표시된 이 주석의 끝에 해당하는 타임스탬프(YYYY-MM-DDThh:mmTZD). 예를 들어: "2025-11-10T07:00:00+01:00".

응답

json
{
  "data": {
    "id": 12345,
    "start": "2025-11-01T07:00:00+00:00",
    "details": "This marks the release of feature X",
    "category": {
      "id": 45678,
      "name": "Releases"
    },
    "end": "2025-11-10T07:00:00+01:00",
    "label": "Feature X Release",
    "chart_id": null
  }
}

오류 응답

  • 400 - 잘못된 필드
  • 404 - 범주를 찾을 수 없습니다.

모든 주석 가져오기

프로젝트의 모든 차트 주석을 검색합니다. 범주, 차트 및 날짜 범위별로 필터링할 수 있습니다.

curl --location --request GET 'https://amplitude.com/api/3/annotations?category=Releases&start=2025-11-01T07:00:00+00:00&end=2025-11-30T07:00:00+00:00' \
-u '{api-key}:{secret-key}'

쿼리 매개 변수

매개 변수설명
category선택 사항입니다. 문자열입니다. 지정된 경우 이 범주의 주석만 반환됩니다. chart_id 필터와 결합되지 않습니다.
chart_id선택 사항입니다. 문자열입니다. 지정된 경우 이 차트에 표시된 주석만 반환됩니다. category 필터와 결합되지 않습니다.
start선택 사항입니다. 문자열입니다. 지정된 경우 ISO 8601 형식(YYYY-MM-DDThh:mmTZD)인 start 이후에 발생하는 주석만 반환합니다. 예를 들어: "2025-11-10T07:00:00+01:00".
end선택 사항입니다. 문자열입니다. 지정된 경우, ISO 8601 형식(YYYY-MM-DDThh:mmTZD)인 end 이전에 생성된 주석만 반환합니다. 주석이 날짜 범위에 걸쳐 있는 경우 주석의 종료 날짜는 end 입력 이전이어야 합니다. 예를 들어: "2025-11-10T07:00:00+01:00".

응답

json
{
  "data": [
    {
      "id": 12345,
      "start": "2025-11-01T07:00:00+00:00",
      "details": "This marks the release of feature X",
      "category": {
        "id": 45678,
        "name": "Releases"
      },
      "end": "2025-11-10T07:00:00+01:00",
      "label": "Feature X Release",
      "chart_id": null
    }
  ]
}

오류 응답

  • 400 - 잘못된 요청
  • 409 - 충돌

단일 주석 가져오기

ID별로 단일 차트 주석을 검색합니다.

curl --location --request GET 'https://amplitude.com/api/3/annotations/:annotation_id' \
-u '{api-key}:{secret-key}'

경로 매개변수

매개 변수설명
annotation_id필수입니다. 정수입니다. 검색할 주석의 ID입니다.

응답

json
{
  "data": {
    "id": 12345,
    "start": "2025-11-01T07:00:00+00:00",
    "details": "This marks the release of feature X",
    "category": {
      "id": 45678,
      "name": "Releases"
    },
    "end": "2025-11-10T07:00:00+01:00",
    "label": "Feature X Release",
    "chart_id": null
  }
}

오류 응답

  • 400 - 잘못된 주석 ID
  • 404 - 주석을 찾을 수 없습니다.

주석 업데이트

특정 주석을 업데이트합니다. 부분 업데이트를 지원합니다. 요청 본문에 지정한 필드만 업데이트됩니다.

curl --location --request PUT 'https://amplitude.com/api/3/annotations/:annotation_id' \
--header 'Authorization: Basic {api-key}:{secret-key}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "label": "Updated Feature X Release",
  "end": "2025-11-15T07:00:00+01:00"
}'

경로 매개변수

매개 변수설명
annotation_id필수입니다. 정수입니다. 업데이트할 주석의 ID입니다.

바디 매개변수

매개 변수설명
label선택 사항입니다. 문자열입니다. 주석의 제목입니다.
start선택 사항입니다. 문자열입니다. 이 주석의 시작에 해당하는 타임스탬프는 ISO 8601 형식(YYYY-MM-DDThh:mmTZD)입니다. 예를 들어: "2025-11-01T07:00:00+00:00".
category선택 사항입니다. 문자열입니다. 주석이 속한 범주의 이름입니다.
chart_id선택 사항입니다. 문자열입니다. 주석을 달 차트의 ID(URL에서 찾을 수 있음)입니다. chart_id을(를) 포함하지 않을 경우 주석은 전역적이며 프로젝트의 모든 차트에 나타납니다. 특정 차트와의 연관성을 제거하고 주석을 전체적으로 표시하려면 null(으)로 설정합니다.
details선택 사항입니다. 문자열입니다. 주석에 대한 세부 정보입니다.
end선택 사항입니다. 문자열입니다. ISO 8601 형식으로 표시된 이 주석의 끝에 해당하는 타임스탬프(YYYY-MM-DDThh:mmTZD)입니다. 예를 들어: "2025-11-10T07:00:00+01:00". 종료 시간을 제거하려면 null으(로) 설정합니다.

응답

json
{
  "data": {
    "id": 12345,
    "start": "2025-11-01T07:00:00+00:00",
    "details": "This marks the release of feature X",
    "category": {
      "id": 45678,
      "name": "Releases"
    },
    "end": "2025-11-15T07:00:00+01:00",
    "label": "Updated Feature X Release",
    "chart_id": null
  }
}

오류 응답

  • 400 - 잘못된 필드
  • 404 - 주석을 찾을 수 없습니다.
  • 404 - 범주를 찾을 수 없습니다.

주석 삭제

curl --location --request DELETE 'https://amplitude.com/api/3/annotations/:annotation_id' \
-u '{api-key}:{secret-key}'

경로 매개변수

매개 변수설명
annotation_id필수입니다. 정수입니다. 삭제할 주석의 ID입니다.

응답

json
{
  "success": true
}

오류 응답

  • 400 - 잘못된 주석 ID
  • 404 - 주석을 찾을 수 없습니다.

이 내용이 도움이 되었나요?