Shaped APIs

Shaped provides two APIs that you should be familiar with to get started:

  • Model API
  • Rank API

Model API

The Model API allows you to manage your ranking models. It provides endpoints to create, list and delete your models. It can be hit without writing any explicit code — simply make a curl request from command line to get started.

For example, say you want to build a video recommendation model. You have three relevant tables stored in your BigQuery data warehouse:

  • user - contains your user rows and their demographic attributes
  • video - contains the video rows and their metadata attributes
  • event - contains the user click and impression events for each video

For this example we'll get started by just creating a model from the interactions table. Often our users start this way and enrich their schema with the user and item attributes later. Here is the corresponding schema for the interaction table stored in BigQuery above:

$ curl --request POST '' \
--header 'x-api-key: <YOUR-API-KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "model_name": "video_recs",
    "connector_configs": [{
        "type": "BigQuery",
        "location": "us-west1 ",
        "project_id": "rocket-ship-234123"
    "schema": {
        "user": {
            "id:" "user_id",
        "item": {
            "id": "video_id",
        "interaction": {
            "created_at": "event_timestamp",
            "label": {
                "type": "Binary",
                "name": "clicked"
            "source": {
                "connector_id": "bigquery", 
                "query": "select * from video_db.click_events"

Once this curl request is made your model is created. Depending on how many interactions you provide, it’ll take up to a few hours to train before you can start retrieving ranked results from the Rank API.

Rank API

The Rank API is what you use to retrieve results from your ranking model. It is a real-time API designed to be integrated directly into your application.

curl "" \
     --header "x-api-key: <YOUR-API-KEY>"
# Response: [427010, 182094, 332874, 82791, 40352, 389299, 462470, 415711, 413870, 463499]

Here’s an example curl request fetching 10 ranked videos for the user with id 3. The response is a list of the 10 most relevant video ids for that user. Note that the rank endpoint only returns ids for items that haven’t been seen before (based off the interactions schema view).

The rank API responds to requests in under 200 milliseconds for US East cloud regions.

Data access

Shaped needs access to all the data that you map within your schema. We provide different ways to share this access based on the cloud platform or data stack type. For a BigQuery connection, like in the example above, you must share data read access to the Shaped Google Cloud Platform service account, which we’ll share alongside the API key. More details about sharing data access to each cloud platform can be found here.

If your data stack is within a firewall, you will need to whitelist the the public IPs of our model generating machines. We'll send you these IPs with your API key when you sign up.

How to get an API key?

Please contact us at [email protected] to get started with the API. We’ll send you an API key that you can use to setup models and start fetching results. We’re interested in supporting any of your ranking use-cases so don’t hesitate to get in touch.