はじめに

DANGER

このAPIは現在ベータ版です。エンドポイント、パラメータ、レスポンス形式は予告なく変更される場合があります。

YouViCo APIを使うと、自社ツールやワークフローからチームのプロジェクト、フォルダー、ファイル、コメントを読み取り、操作する連携を構築できます。

APIでできること:

• プロジェクトを検索し、フォルダーとファイルを取得する
• フォルダーとファイルを作成、更新、削除する
• ファイルのコメントを読み書きする
• 絵文字リアクションを追加または削除する
• ファイルのレビュータグを更新する

すべてのAPIアクセスには、特定のワークスペースに紐づくAPIキーが必要です。

Base URL

すべてのリクエストは次のURLに送信します。

https://api.youvico.com/api

APIキーを取得する

YouViCoアプリのAPIキー設定で新しいキーを作成します。用途が分かる名前を付け、アクセス対象のワークスペースを選択してください。

WARNING

APIキーは作成時に 一度だけ 表示されます。ページを離れると再表示できません。すぐにコピーし、安全な場所に保管してください。

キーは秘密情報です。クライアント側コードや公開リポジトリに含めないでください。キーが漏えいした場合は削除して新しいキーを発行してください。

認証

各リクエストの Authorization ヘッダーにBearerトークンとしてAPIキーを含めます。

Authorization: Bearer YOUR_API_KEY

ローカルワークフローではCLIを使う

ターミナル作業や簡単な確認には、YouViCo CLIをインストールしてAPIキーをローカルに保存してください。

npm install -g @youvico/cli
youvico auth api

認証後は、APIリファレンスの CLI タブにある例をそのまま実行できます。

youvico project search --query "launch"

設定、コマンドグループ、ファイルアップロード、スクリプトでの使い方については CLIガイド を参照してください。

簡単に始めるにはSDKを使う

サーバーサイドのJavaScriptまたはTypeScriptで連携を作る場合は、JavaScript SDKから始めるのがおすすめです。SDKが認証ヘッダー、型付きのリクエストパラメータとレスポンス、エラー処理、マルチパートアップロードの流れを処理します。

pnpm add @youvico/api

import { Client } from "@youvico/api";

const client = new Client({
  apiKey: process.env.YOUVICO_API_KEY!,
});

const projects = await client.projects.search({
  query: "launch",
});

インストール、クライアントオプション、アップロードヘルパー、エラー処理については SDKガイド を参照してください。

リクエスト形式

APIはRESTの慣例に従います。エンドポイントは JSON を受け取り、JSONを返します。

本文を持つリクエスト（POST、PATCH、DELETE）では Content-Type ヘッダーを設定してください。

Content-Type: application/json

レスポンス形式

本文を持つ成功レスポンスは、結果を data フィールドでラップします。

{
  "data": {
    "id": "bdbff5de-96d7-468f-9db0-85fe28bd6b62",
    "name": "Launch Campaign"
  }
}

一覧エンドポイントは data を配列で返します。ページネーションを使う一覧エンドポイントは page オブジェクトも含めます。

{
  "data": [ ... ],
  "page": {
    "current": 1,
    "hasNext": true
  }
}

更新、削除、アップロード完了、レビュータグ更新、リアクションなど一部の書き込みエンドポイントは、成功時に本文なしの 204 No Content を返します。

エラーレスポンス

問題が発生した場合、APIは適切なHTTPステータスコードとJSONエラー本文を返します。

{
  "message": "プロジェクトが見つかりません。",
  "code": "PROJECT_NOT_FOUND_EXCEPTION"
}

エラーコードの一覧は エラーとレート制限 を参照してください。

型表記

APIリファレンスのフィールド項目では、次の型表記を使用します。

表記	意味
string	その型の必須値で、null は不可
string?	null を許容する値

required バッジがないフィールドはリクエストで省略できます。

次のステップ

• SDK — JavaScriptクライアント設定とエンドポイント例
• CLI — コマンドライン設定とローカルワークフロー
• 認証 — ワークスペースアクセスとキー権限
• エラーとレート制限 — エラーコードとスロットリング
• ページネーション — オフセットページネーションとカーソルページネーション
• APIリファレンス — 全エンドポイントドキュメント