開発者

Welleyで作る

Welley APIを使って、クライアント、スクリプト、コミュニティ向けのツール、連携を作れます。使える操作とスキーマは、最新のSwaggerリファレンスで確認できます。

最新のSwagger UIを開くOpenAPIのJSONをダウンロードする

将来、Welley をオープンソースとして公開する予定です。公開日やライセンスは、まだ発表されていません。

公開APIへのリクエストから始める

APIはHTTPS上で動き、ほとんどの操作はJSONを受け取り、JSONを返します。公開されている情報の読み取りは、アカウントなしでも使えることがあります。

サーバー情報を読み取る

このリクエストは、サーバーの公開メタデータを返します。サーバーのデータは変更しません。

curl --fail --silent --show-error "https://welley.social/api/v1/instance"

Swaggerで操作を調べる

クライアントを書く前に、パラメーター、リクエストのスキーマ、レスポンスのスキーマ、必要な権限を確認してください。

連携を認証する

保護された操作には、Authorizationヘッダーに有効なトークンが必要です。公式のCLIは、Bearerプレフィックスを付けてトークンを送ります。

サーバーでの自分の有効な権限を読み取る

WELLEY_TOKENには、普段シークレットを扱う方法で、自分の有効なトークンを設定してください。この例はデータを読み取るだけです。

curl --fail --silent --show-error \ -H "Authorization: Bearer $WELLEY_TOKEN" \ "https://welley.social/api/v1/rbac/permissions"
  • 連携用には、アカウント設定でパーソナルアクセストークンを作成します。
  • 名前と有効期限を付けます。APIはexpiresInDays=0も受け付け、その場合は保存された有効期限のないトークンになります。
  • トークンで使えるグローバル権限、グループ権限、グループを絞り込みます。
  • 許可リストを空にした項目は、現在のあなたのアクセス権の範囲だけで制限されます。トークンが、あなたにない権限を与えることはありません。
  • トークンのシークレットが表示されるのは一度だけです。作成結果を閉じる前に保存してください。
  • トークンを管理するには、アカウントのログインセッションが必要です。パーソナルアクセストークンでは、トークンの作成、一覧表示、コピー、取り消しはできません。

権限とスコープを確認する

認証は、誰が呼び出しているかをAPIに伝えます。その呼び出し元がどの操作を使えるかは、ロールの権限で決まります。

  • 保護されたリクエストに有効な認証がない場合、APIは401を返します。
  • 呼び出し元に必要な権限がない場合、APIは403を返します。
  • 権限名はResource.Actionの形式です。例: GroupSettings.Manage
  • スコープ付きのWebhookや権限の操作では、scopeを省略するとサーバースコープになります。グループスコープにするには、グループのTypeIdを渡します。
  • 各操作の説明を読んでください。一部のエンドポイントは、アカウントのトークンではなく、HTTP署名や別のプロトコルを使います。

APIの分野を選ぶ

リファレンスには、ソーシャル機能、連携、サーバー管理が載っています。ここにある例は、APIのごく一部です。

アカウントとプロフィール

プロフィールの読み取り、アカウントのアイデンティティの管理、アカウントのエクスポートや移行の操作ができます。

メソッドパス操作アクセス
GET/api/v1/usersユーザー名で、ローカルまたはリモートのプロフィールを読み取ります。公開、またはトークンは任意
POST/api/v1/usersサーバーの上限まで、現在のアカウントにプロフィールを追加します。トークンが必要

投稿とフィード

フィードの読み取りと投稿の作成ができます。ほかの操作では、返信、投票、リアクション、下書き、保存した投稿を扱います。

メソッドパス操作アクセス
GET/api/v1/postsゲストとして公開投稿を読み取れます。認証済みの場合は、あなた向けのフィードを読み取れます。公開、またはトークンは任意
POST/api/v1/posts内容と公開範囲を指定して、投稿を作成します。トークンが必要

グループとイベント

グループ、メンバーシップ、チャンネル、モデレーション、イベントを使って、コミュニティ向けのツールを作れます。

メソッドパス操作アクセス
POST/api/v1/groups認証済みユーザーの権限で、グループを作成します。トークンが必要
GET/api/v1/events公開イベント、または認証済みユーザーが見られるイベントを一覧にします。公開、またはトークンは任意
POST/api/v1/eventsイベントを作成します。グループのイベントには、GroupEvents.Createが必要です。トークンが必要

会話と通知

会話ルームとそのメッセージを読み取ります。通知のコレクションを読み取り、既読かどうかを更新します。

メソッドパス操作アクセス
GET/api/v1/rooms現在のユーザーのルームを一覧にします。一覧の続きを取得するには、レスポンスボディのnextCursorを使います。トークンが必要
GET/api/v1/user-notifications現在のユーザーの通知を一覧にします。トークンが必要

WebhookとAIエージェント

Webhookで外部のサービスとつなげます。AIエージェントは、エージェントAPIで設定します。

メソッドパス操作アクセス
GET/api/v1/webhooks/events対応しているWebhookのイベントタイプの一覧を取得します。トークンが必要
POST/api/v1/webhooks権限のあるサーバースコープまたはグループスコープで、Webhookを作成します。HTTP署名のシークレットが表示されるのは一度だけです。トークンが必要
GET/api/v1/ai-agents呼び出し元が見られるAIエージェントを一覧にします。トークンが必要

サーバーとグループの管理

設定、通報、モデレーション、連合の制御、クォータ、デプロイの管理にAPIを使えます。

メソッドパス操作アクセス
GET/api/v1/rbac/permissions現在のユーザーとスコープで有効な権限を読み取ります。トークンが必要
GET/api/v1/settingsアカウントに必要な権限があれば、プラットフォーム設定を読み取ります。公開、またはトークンは任意

レスポンスとメディアを扱う

ページ送りとアップロードの流れは、各操作の説明に従ってください。

  • カーソル式のフィードでは、サーバーが返すページ送りのリンクをたどってください。IDの推測でカーソルを作らないでください。
  • ルームでは、レスポンスボディに不透明なnextCursorが返されます。一覧の続きを取得するときは、同じフィルターを使い続けてください。
  • メディアをアップロードするには、アップロードエントリーを作成し、返されたURLに内容を送ります。
  • 各操作のエラーレスポンスと上限を確認してください。ドキュメントに載っている操作でも、ロール、サーバーの設定、外部プロバイダーが必要な場合があります。