English
日本語
한국어

日本語

English
한국어

Appearance

ガイド

はじめに ​

DANGER

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

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

APIでできること:

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

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

ベースURL ​

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

https://api.youvico.com/api

プロジェクトを検索する例:

GET https://api.youvico.com/api/projects/search

APIキーを取得する ​

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

WARNING

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

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

認証 ​

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

Authorization: Bearer YOUR_API_KEY

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

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

bash
npm install -g @youvico/cli
youvico auth api

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

bash
youvico project search --query "launch"

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

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

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

bash
pnpm add @youvico/api
ts
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

典型的なリクエストは次のようになります。

bash
curl -X POST 'https://api.youvico.com/api/files/:id/comments' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "content": "Looks great, approved." }'

レスポンス形式 ​

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

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

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

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

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

エラーレスポンス ​

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

json
{
  "statusCode": 404,
  "message": "Not found"
}

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

型表記 ​

APIリファレンスの表では、次の型表記を使用します。

表記意味
stringその型の必須かつ非nullの値
string?nullable — 値が null の場合があります
Required: No省略可能 — リクエストでフィールドまたはパラメータを省略できます

次のステップ ​

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