http api

ダッシュボードでできることを、ターミナルから

アカウントキーが一つ。サイトの一覧、デプロイ、名前の変更、フォームが集めた内容の取得、削除まで — 素の HTTP で、スクリプトからも、CI ジョブからも、エージェントからも。

クイックスタート

コマンドは三つ

ダッシュボードでキーを作り、動くことを確かめて、フォルダを公開します。キーは毎回 Authorization ヘッダーに入れます。

キーが使えるか確かめる

curl -H "Authorization: Bearer hvs_…" https://harvis.dev/api/v1

アカウントの中身を見る

curl -H "Authorization: Bearer hvs_…" https://harvis.dev/api/v1/sites

フォルダを公開する

curl -X POST https://harvis.dev/api/v1/sites \
  -H "Authorization: Bearer hvs_…" \
  -F "files=@index.html" -F "paths=index.html"

一つの契約

ウェブアプリと API がずれることはありません

機能は一つのファイルで一度だけ宣言され、ダッシュボードもこの API もそこから作られます。openapi.json はその宣言から生成され、食い違えばビルドが失敗します。つまりこれは製品を説明する文書ではなく — 製品そのものを形づくっているものです。

機能ごとに実装は一つ。ウェブアプリもあなたのスクリプトも同じものを呼びます。
openapi.json は生成されるもので、手書きされることはなく、/openapi.json で配信されます。
ルートと契約とドキュメントが食い違った時点で、ビルドは失敗します。

デプロイ

キーがあれば、サイトは最初からあなたのもの

アカウントなしのデプロイはこれからも使えます — 後で開くための非公開のクレームリンクが返ります。同じ呼び出しにキーを添えれば、引き取るものは何もありません。最初の 1 バイトからサイトはアカウントの中にあり、期限も切れません。

zip -r site.zip . && curl -X POST https://harvis.dev/api/upload \
  -H "Authorization: Bearer hvs_…" \
  -H "Content-Type: application/zip" --data-binary @site.zip

エンドポイント

すべての面

リクエストとレスポンスの完全な形は OpenAPI ドキュメントにあります。

メソッド	パス	内容
GET	/api/v1	Check that a credential works.
GET	/api/v1/keys	The account's API keys. Revoked keys are not listed.
POST	/api/v1/keys	Create an API key.
DELETE	/api/v1/keys/{keyId}	Revoke an API key. Anything using it stops working immediately.
GET	/api/v1/me	The account a credential belongs to.
GET	/api/v1/sites	List the account's sites, newest first.
POST	/api/v1/sites	Create a site from a folder of files.
DELETE	/api/v1/sites/{id}	Delete a site, its files and its form submissions.
GET	/api/v1/sites/{id}	One site.
PATCH	/api/v1/sites/{id}	Rename a site, change its web address, or both.
POST	/api/v1/sites/{id}/deploy	Replace every file of a site with the uploaded set.
POST	/api/v1/sites/{id}/deploy-token	Issue a new deploy token for a site. The old one stops working immediately.
POST	/api/v1/sites/{id}/deploy/zip	Replace every file of a site from a zip archive sent as the raw request body.
GET	/api/v1/sites/{id}/files	Every file a site is serving.
POST	/api/v1/sites/{id}/files	Add or overwrite individual files, leaving the rest of the site alone.
DELETE	/api/v1/sites/{id}/submissions	Delete every submission for a site, or every one of a single form.
GET	/api/v1/sites/{id}/submissions	One page of a site's form submissions, newest first.
DELETE	/api/v1/sites/{id}/submissions/{submissionId}	Delete one submission.
GET	/api/v1/sites/{id}/submissions/{submissionId}	One submission.
GET	/api/v1/sites/{id}/submissions/csv	Export a site's form submissions as CSV.
POST	/api/v1/sites/{id}/submissions/read	Mark every unread submission as read.
GET	/api/v1/sites/{id}/submissions/summary	How many submissions a site holds, how many are unread, and which forms exist.

エラー

失敗はすべて同じ形

分岐はコードで行い、メッセージでは行わないでください。コードは安定していて、文章はログを読む人のためのものです。

{
  "error": {
    "code": "subdomainTaken",
    "message": "That address is already taken. Try another."
  }
}