リファレンス

REST API

自分のコードから、投稿の作成、予約、公開、メディアのアップロード、成果の取得ができます。APIはSPREVA本体と同じルールと検証に従います。

最初のリクエスト

1
SPREVAの開発者、APIキーの順に開いてAPIキーを作成します。この例には「読み取り専用」のキーで十分です。公開するには「公開」の権限を持つキーが必要です。

SNSアカウントを一覧にします。

ターミナル

curl https://dev-app.spreva.ai/api/v1/social-accounts \
  -H "Authorization: Bearer spreva_sk_..."

3
応答を読みます。結果はdataの中に入っています。アカウントのidは、そのアカウント向けの投稿を作成するときにconnectionIdとして渡す値です。サンプルは省略しており、実際のオブジェクトにはさらに多くのフィールドがあります。
JSON
```
{
  "data": [
    {
      "id": "e81b3f52-0000-4000-8000-000000000005",
      "provider": "instagram",
      "displayName": "Acme Studio",
      "username": "acme",
      "status": "ACTIVE",
      "needsReconnect": false
    }
  ]
}
```

基本

すべてのエンドポイントはこのアドレスの下にあります。JSONを送り、キーはAuthorization: Bearerの後に続けて指定します。

URL

https://dev-app.spreva.ai/api/v1

キーは1つのワークスペースに属し、そのワークスペースしか見られません。
上限：ワークスペース内の1人につき1分間に120リクエストで、その人が作成したすべてのキーで共有します。超えると429が返され、メッセージに待つべき秒数が示されます。
エラーは、リクエストのAccept-Languageヘッダーの言語で返されます。codeは変わりません。
SPREVAにログインしたブラウザからは、キーの代わりにx-workspace-idでワークスペースのIDを送ります。

キーと権限

キーは作成した人の代理として動作し、その人のロールで許可されている以上のことはできません。キーを作成できるのは、API利用を含むプランのオーナーと管理者で、キー全体が表示されるのは一度だけです。各キーには、付与された権限があります。

posts:read: 投稿、そのステータス、結果、キューを閲覧
media:read: メディアライブラリを閲覧
accounts:read: 連携済みのSNSアカウントを閲覧
analytics:read: 分析を閲覧
posts:write: 投稿の作成、編集、予約、公開、削除、キューの管理
media:write: メディアのアップロード、名前の変更、削除
webhooks:write: Webhookエンドポイントの閲覧と追加
ai:write: AIの利用。キャプションとハッシュタグにはposts:writeも、代替テキストと画像にはmedia:writeも必要です

読み取り専用は4つの読み取り権限を付与します。公開はさらにposts:write、media:write、ai:writeを加えたもので、自動化やAIエージェントにはこれで十分です。403は、キーに権限がないか、作成者のロールがもう許可していないことを意味します。

キーもエージェントも、投稿を承認することは決してできません。承認が必要なワークスペースでは、承認するのはSPREVA上の人だけです。

エラー

すべてのエラーは同じ形をしています。分岐にはcodeを使い、表示にはmessageを使ってください。

JSON

{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key needs the posts:write scope for posts:create"
  }
}

400: INVALID_REQUEST, INVALID_JSON, WORKSPACE_REQUIRED
ボディまたはクエリがエンドポイントと一致しません。detailsに、間違っている各フィールドが示されます。x-workspace-idのないブラウザからの呼び出しにはWORKSPACE_REQUIREDが返されます。
401: UNAUTHENTICATED
キーがないか、入力が間違っているか、取り消されたか、有効期限が切れています。「Authorization: Bearer <key>」を送ってください。
402: ENTITLEMENT_EXCEEDED, AI_LIMIT_REACHED
ワークスペースに有効なプランがないか、AIクレジットが残っていないか、プランにこの機能が含まれていません。オーナーが「設定」、「請求」の順に開いて、プランを選ぶかクレジットを購入できます。
403: FORBIDDEN
キーにこのリクエストの権限がないか、自分のロールでは許可されていません。より広いアクセス権を持つキーを作成してください。
404: NOT_FOUND
このワークスペースにそのオブジェクトはありません。キーが見られるのは、作成されたワークスペースだけです。
409: CONCURRENT_MODIFICATION, INVALID_STATE_TRANSITION, CONFLICT, AI_NOT_CONFIGURED, REVIEW_REQUIRED
読み取った後に投稿が変更されたか、この操作を許可しない状態にある（公開済みの投稿を公開するなど）か、削除しようとしているファイルがまだ投稿で使われているか、このインストールでAIが設定されていません。もう一度取得して再試行してください。REVIEW_REQUIREDは別です。ワークスペースが公開前の承認を求めているので、再試行せずにPOST /posts/{id}/reviewで投稿をレビューに回してください。
422: VALIDATION_FAILED, PROVIDER_VALIDATION_FAILED, AI_REFUSED
内容が公開先のアカウントに合っていないか、AIのリクエストが拒否されました。GET /providersで各SNSのルールを確認できます。
429: RATE_LIMITED, AI_BUSY
このワークスペースで1分間に120を超えるリクエストを送ったか、同時に送ったAIのリクエストが多すぎます。RATE_LIMITEDの場合はメッセージに待つべき秒数が示されます。AI_BUSYの場合は少し待ってください。
500: INTERNAL
SPREVAまたはSNSで、リクエストの処理中に問題が発生しました。少し待ってから再試行してください。
503: AI_UNAVAILABLE
AIプロバイダーが現在利用できません。少し待ってから再試行してください。

エンドポイント

パスはベースURLからの相対パスです。OpenAPIドキュメントにすべてのボディとパラメーターが記述されており、そこからクライアントを生成できます。

URL

https://dev-app.spreva.ai/api/openapi.json

SNSアカウントとSNS

get /social-accounts連携済みのSNSアカウント。
get /providers各SNSのルール：フォーマット、掲載面、上限。

投稿

get /posts投稿。ステータス、日付、アカウント、SNS、キャンペーンで絞り込めます。
post /posts1つ以上のアカウント向けに下書きの投稿を作成します。
get /posts/{id}アカウント、検証結果、メディアを含む投稿。
patch /posts/{id}投稿を変更します。読み取ったversionを送ってください。その後に変更されていた場合、応答は409になります。
delete /posts/{id}投稿を削除します。
post /posts/{id}/publish今すぐ公開します。応答は202です。結果は投稿を追跡するか、Webhookで確認してください。
post /posts/{id}/scheduleタイムゾーンを指定して、日時に予約します。
post /posts/{id}/queueキューの次の空き枠に追加します。
post /posts/{id}/review日時かキューを指定してレビューに回します。承認されると公開されます。
post /posts/{id}/retry失敗したアカウントで再試行します。

メディア

get /mediaライブラリ。検索と絞り込みができます。
post /media/uploadsアップロードを開始します。応答に、ファイルの送信先が示されます。
post /media/uploads/{id}/completeアップロードを完了します。その後、ファイルがチェックされ、処理されます。
get /media/{id}ファイルと、そのステータス、判明している情報。
delete /media/{id}ファイルを削除します。投稿でまだ使われているファイルでは409が返されます。
put /media/{id}/alt-textファイルの代替テキストを保存または消去します。
post /media/{id}/alt-text/suggestionAIで代替テキストを提案します。保存はしません。

分析

get /analytics期間内の成果。
get /analytics/export同じ成果をCSVファイルで。

キュー

get /queues投稿キュー。
post /queues毎週の投稿枠を指定してキューを作成します。
patch /queues/{id}キューを変更します。
delete /queues/{id}キューを削除します。

Webhook

get /webhooksWebhookのエンドポイント。
post /webhooksエンドポイントを追加します。応答にはこの一度だけ、シークレットが含まれます。

get /aiAIが使えるかどうか、残りのクレジット、各操作のコスト。
post /ai/captionsキャプションの書き直し、翻訳、ハッシュタグを提案します。保存はしません。
post /ai/images画像を生成します。準備ができるまでGET /media/{id}を問い合わせてください。