godot-asset-library/API.md

Asset library API

All POST APIs accept JSON-encoded or formdata-encoded bodies. GET APIs accept standard query strings.

Core

The core part of the API is understood and used by the C++ frontend embedded in the Godot editor. It has to stay compatible with all versions of Godot.

• GET /configure - get details such as category and login URL
• GET /asset?… - list assets by filter
• GET /asset/{id} - get asset by id

Auth API

POST /register

{
  "username": "(username)",
  "password": "(password)",
  "email": "(email)"
}

Successful result:

{
  "username": "(username)",
  "registered": true
}

Register a user, given a username, password, and email.

POST /login

{
  "username": "(username)",
  "password": "(password)"
}

Successful result:

{
  "authenticated": true,
  "username": "(username)",
  "token": "(token)"
}

Login as a given user. Results in a token which can be used for authenticated requests.

POST /logout

{
  "token": "(token)"
}

Successful result:

{
  "authenticated": false,
  "token": ""
}

Logout a user, given a token. The token is invalidated in the process.

POST /change_password

{
  "token": "(token)",
  "old_password": "(password)",
  "new_password": "(new password)"
}

Successful result:

{
  "token": ""
}

Change a user's password. The token is invalidated in the process.

GET /configure

?type=(any|addon|project)
&session

Example result:

{
  "categories": [
    {
      "id": "1",
      "name": "2D Tools",
      "type": "0"
    },
    {
      "id": "2",
      "name": "Templates",
      "type": "1"
    },
  ],
  "token": "…",
  "login_url": "https://…"
}

Get a list of categories (needed for filtering assets) and potentially a login URL which can be given to the user in order to authenticate him in the engine (currently unused and not working).

Assets API

GET /asset?…

?type=(any|addon|project)
&category=(category id)
&support=(official|community|testing)
&filter=(search text)
&user=(submitter username)
&godot_version=(major).(minor).(patch)
&max_results=(number 1…500)
&page=(number, pages to skip) OR &offset=(number, rows to skip)
&sort=(rating|cost|name|updated)
&reverse

Example response:

{
  "result": [
    {
      "asset_id": "1",
      "title": "Snake",
      "author": "test",
      "author_id": "1",
      "category": "2D Tools",
      "category_id": "1",
      "godot_version": "2.1",
      "rating": "0",
      "cost": "GPLv3",
      "support_level": "testing",
      "icon_url": "https://….png",
      "version": "1",
      "version_string": "alpha",
      "modify_date": "2018-08-21 15:49:00"
    }
  ],
  "page": 0,
  "pages": 0,
  "page_length": 10,
  "total_items": 1
}

Get a list of assets.

Some notes:

• For legacy purposes, not supplying godot version would list only 2.1 assets, while not supplying type would list only addons.
• To specify multiple support levels, join them with +, e.g. support=official+community
• Godot version can be specified as you see fit, for example, godot_version=3.1 or godot_version=3.1.5. Currently, the patch version is disregarded, but may be honored in the future.

GET /asset/{id}

No query params. Example result:

{
  "asset_id": "1",
  "type": "addon",
  "title": "Snake",
  "author": "test",
  "author_id": "1",
  "version": "1",
  "version_string": "alpha",
  "category": "2D Tools",
  "category_id": "1",
  "godot_version": "2.1",
  "rating": "0",
  "cost": "GPLv3",
  "description": "Lorem ipsum…",
  "support_level": "testing",
  "download_provider": "GitHub",
  "download_commit": "master",
  "download_hash": "(sha256 hash of the downloaded zip)",
  "browse_url": "https://github.com/…",
  "issues_url": "https://github.com/…/issues",
  "icon_url": "https://….png",
  "searchable": "1",
  "modify_date": "2018-08-21 15:49:00",
  "download_url": "https://github.com/…/archive/master.zip",
  "previews": [
    {
      "preview_id": "1",
      "type": "video",
      "link": "https://www.youtube.com/watch?v=…",
      "thumbnail": "https://img.youtube.com/vi/…/default.jpg"
    },
    {
      "preview_id": "2",
      "type": "image",
      "link": "https://….png",
      "thumbnail": "https://….png"
    }
  ]
}

Notes:

• The cost field is the license. Other asset libraries may put the price there and supply a download URL which requires authentication.
• The download_hash field is always empty and is kept for compatibility only.
• The download URL is generated based on the download commit and the browse URL.

POST /asset/{id}/delete

{
  "token": "…"
}

Successful response:

{
  "changed": true
}

Soft-delete an asset. Useable by moderators and the owner of the asset.

POST /asset/{id}/undelete

{
  "token": "…"
}

Successful response:

{
  "changed": true
}

Revert a deletion of an asset. Useable by moderators and the owner of the asset.

POST /asset/{id}/support_level

{
  "support_level": "official|community|testing",
  "token": "…"
}

Successful response:

{
  "changed": true
}

API used by moderators to change the support level of an asset.

Asset edits API

POST /asset, POST /asset/{id}, POST /asset/edit/{id}

{
  "token": "…",

  "title": "Snake",
  "description": "Lorem ipsum…",
  "category_id": "1",
  "godot_version": "2.1",
  "version_string": "alpha",
  "cost": "GPLv3",
  "download_provider": "GitHub",
  "download_commit": "master",
  "browse_url": "https://github.com/…",
  "issues_url": "https://github.com/…/issues",
  "icon_url": "https://….png",
  "download_url": "https://github.com/…/archive/master.zip",
  "previews": [
    {
      "enabled": true,
      "operation": "insert",
      "type": "image|video",
      "link": "…",
      "thumbnail": "…"
    },
    {
      "enabled": true,
      "operation": "update",
      "edit_preview_id": "…",
      "type": "image|video",
      "link": "…",
      "thumbnail": "…"
    },
    {
      "enabled": true,
      "operation": "delete",
      "edit_preview_id": "…"
    },
  ]
}

Successful result:

{
  "id": "(id of the asset edit)"
}

Create a new edit or update an existing one. Fields are required when creating a new asset, and are optional otherwise. Same for previews -- required when creating a new preview, may be missing if updating one.

Notes:

• Not passing "enabled": true for previews will result in them not being included in the edit. This may be fixed in the future.
• version_string is free-form text, but major.minor or major.minor.patch format is best.
• Available download providers can be seen on the asset library fronted.

GET /asset/edit/{id}

No query params. Example result:

{
  "edit_id": "1",
  "asset_id": "1",
  "user_id": "1",
  "title": null,
  "description": null,
  "category_id": null,
  "godot_version": null,
  "version_string": null,
  "cost": null,
  "download_provider": null,
  "download_commit": null,
  "browse_url": "…",
  "issues_url": "…",
  "icon_url": null,
  "download_url": "…",
  "author": "test",
  "previews": [
    {
      "operation": "insert",
      "edit_preview_id": "60",
      "preview_id": null,
      "type": "image",
      "link": "…",
      "thumbnail": "…",
    },
    {
      "preview_id": "35",
      "type": "image",
      "link": "…",
      "thumbnail": "…"
    }
  ],
  "original": {
    … original asset fields …
  },
  "status": "new",
  "reason": "",
  "warning": "…"
}

Returns a previously-submitted asset edit. All fields with null are unchanged, and will stay the same as in the original. The previews array is merged from the new and original previews.

POST /asset/edit/{id}/review

{
  "token": "…"
}

Successful result: the asset edit, without the original asset.

Moderator-only. Put an edit in review. It is impossible to change it after this.

POST /asset/edit/{id}/accept

{
  "token": "…",
}

Successful result: the asset edit, without the original asset.

Moderator-only. Apply an edit previously put in review.

POST /asset/edit/{id}/reject

{
  "token": "…",
  "reason": "…"
}

Successful result: the asset edit, without the original asset.

Moderator-only. Reject an edit previously put in review.