NAV Navbar
Logo
shell

Authentication

Request:

curl "https://yoursite.cultivateforecasts.com/oauth/token" \
  -X POST \
  -d grant_type=password \
  -d email=user@example.com \
  -d password=password

Response:

{
  "access_token": "b95b4f848cd226e55b7a42f6a8e8669350730270f5a91d64b6c70328b0156d75",
  "token_type": "bearer",
  "expires_in": 7200,
  "created_at": 1438910165
}

To access the Cultivate Forecasts API, you need an oauth token. You can generate one by making a POST request to /oauth/token with email, password, and grant_type parameters.

HTTP Request

POST https://yoursite.cultivateforecasts.com/oauth/token

Query Parameters

Parameter Value
grant_type password
email Your email address
password Your password

For subsequent requests, you must include your token as part of an authorization header.

Pagination

All list-based endpoints utilize pagination and return only the first page by default. To retrieve subsequent pages, you can append a page parameter to your request (e.g. /api/v1/questions?page=2).

All paginated endpoints will also include 2 pagination-related response headers: X-Total-Page-Count and X-Total-Record-Count. X-Total-Page-Count contains the total number of pages available for your request, while X-Total-Record-Count contains the total number of records that will be included across all of those pages.

Push APIs

Cultivate Forecasts provides push-based APIs for question creation, update, resolution, and clarification.

For each of these APIs, Cultivate Forecasts will make an HTTP POST request to a URL that you specify. The body of the request will contain JSON matching that from the API documentation for each of those models (e.g. a question creation post-hook will contain the question JSON shown here).

To set up a post-hook for any of these APIs, contact Cultivate Labs’ technical support team: tech@cultivatelabs.com

Badges

Badges List

Shows a list of badges that exist on the site.

Request:

curl "https://yoursite.cultivateforecasts.com/api/v1/badges" \
  -H "Authorization: Bearer b95b4f848cd226e55b7a42f6a8e8669350730270f5a91d64b6c70328b0156d75"

Response:

{
  "badges": [
    {
      "id": 1,
      "site_id": 1,
      "name": "Badge name",
      "description": "A description of the badge",
      "image_url": "/uploads/social/badge/image/1/01.png",
      "created_at": "2016-04-18T17:20:51.886Z",
      "updated_at": "2016-04-19T14:39:14.977Z"
    },
    {
      "id": 2,
      "site_id": 1,
      "name": "badge2",
      "description": "another bdage",
      "image_url": "/uploads/social/badge/image/2/badge-image.JPG",
      "created_at": "2016-04-18T17:21:11.025Z",
      "updated_at": "2016-04-18T17:21:11.025Z"
    },
    {
      "id": 3,
      "site_id": 1,
      "name": "A third badge",
      "description": "Third badge description",
      "image_url": "/uploads/social/badge/image/3/badge3.jpg",
      "created_at": "2016-04-18T19:39:43.768Z",
      "updated_at": "2016-04-18T19:39:43.768Z"
    }
  ]
}

HTTP Request

GET https://yoursite.cultivateforecasts.com/api/v1/badges

Query Parameters

None.

Attribute Descriptions

Parameter Type Description
id integer The id of the badge
site_id integer The id of the site this badge belongs to
name string The name of the badge
description string The description of the badge
image_url string URL for the image associated with this badge

Clarifications

Clarifications List

This API returns a list of question clarifications. These are used to officially clarify questions about a question and its resolution criteria. Clarifications are also embedded directly in the question JSON in the questions API.

Request:

curl "https://yoursite.cultivateforecasts.com/api/v1/clarifications" \
  -H "Authorization: Bearer b95b4f848cd226e55b7a42f6a8e8669350730270f5a91d64b6c70328b0156d75"

Response:

{
  "clarifications": [
    {
      "id": 27,
      "question_id": 17,
      "content": "clarification-content-2",
      "created_at": "2016-11-20T22:22:52.724Z",
      "updated_at": "2016-11-27T22:22:52.734Z"
    },
    {
      "id": 28,
      "question_id": 17,
      "content": "clarification-content-3",
      "created_at": "2016-11-26T22:22:52.736Z",
      "updated_at": "2016-11-27T22:22:52.744Z"
    }
  ]
}

HTTP Request

GET https://yoursite.cultivateforecasts.com/api/v1/clarifications

Query Parameters

Parameter Default Description
page 0 Pagination page number

Attribute Descriptions

Parameter Type Description
id integer The id of the clarification
question_id integer The id of the question that is being clarified
content string The actual text of the clarification

Earned Badges

Earned Badge Creation

Creating an “earned badge” model is equivalent to awarding a badge to a given user.

Only administrators can access this API.

Request:

curl -X "POST" "https://yoursite.cultivateforecasts.com/api/v1/earned_badges" \
  -H "Authorization: Bearer b95b4f848cd226e55b7a42f6a8e8669350730270f5a91d64b6c70328b0156d75" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
    -d "{\"earned_badge\":{\"badge_id\":5,\"membership_id\":23}}"

Request body example:

{
  "earned_badge": {
    "badge_id": 5,
    "membership_id": 23
  }
}

Response:

The response contains the newly created earned badge.

{
  "id": 5,
  "badge_id": 5,
  "membership_id": 23,
  "created_at": "2016-04-19T15:09:56.538Z",
  "updated_at": "2016-04-19T15:09:56.538Z",
  "featured": false
}

HTTP Request

POST https://yoursite.cultivateforecasts.com/api/v1/earned_badges

Earned Badge Parameters

Parameter Required? Description
badge_id Yes Contains the ID of the badge to award to the membership.
membership_id Yes Contains the ID of the membership who should be awarded the badge.

Earned Badge Deletion

Deleting an “earned badge” model is equivalent to removing a badge from a given user.

Only administrators can access this API.

Request:

curl -X "DELETE" "https://yoursite.cultivateforecasts.com/api/v1/earned_badges/32" \
  -H "Authorization: Bearer b95b4f848cd226e55b7a42f6a8e8669350730270f5a91d64b6c70328b0156d75" \
  -H "Accept: application/json"

HTTP Request

DELETE https://yoursite.cultivateforecasts.com/api/v1/earned_badges/:id

Earned Badge Parameters

None

Earned Badges List

This endpoint is only accessible to administrators.

Request:

curl "https://yoursite.cultivateforecasts.com/api/v1/earned_badges" \
  -H "Authorization: Bearer b95b4f848cd226e55b7a42f6a8e8669350730270f5a91d64b6c70328b0156d75"

Response:

{
  "earned_badges": [
    {
      "id": 101,
      "badge_id": 110,
      "membership_id": 2726,
      "created_at": "2016-05-02T16:01:34.951Z",
      "updated_at": "2016-05-02T16:01:34.951Z",
      "featured": false
    },
    {
      "id": 100,
      "badge_id": 109,
      "membership_id": 2724,
      "created_at": "2016-05-02T16:01:34.898Z",
      "updated_at": "2016-05-02T16:01:34.898Z",
      "featured": false
    }
  ]
}

HTTP Request

GET https://yoursite.cultivateforecasts.com/api/v1/earned_badges

Query Parameters

Parameter Default Description
page 0 Pagination page number

Attribute Descriptions

Parameter Type Description
id integer The id of the earned badge
badge_id integer The id of the badge that the user earned
featured boolean Users can opt to “feature” some of their badges on their profile. Featured badges are shown on the popover that is displayed when you hover over a user’s username in the web interface.

Memberships

Memberships List

Each user in Cultivate Forecasts has a single user record & user_id. However, a user can be a member of multiple sites. A membership record associates a user to a site. This endpoint provides a list of membership records for a given site and embeds the user record within each membership.

This endpoint is only accessible to site administrators.

Request:

curl "https://yoursite.cultivateforecasts.com/api/v1/memberships" \
  -H "Authorization: Bearer b95b4f848cd226e55b7a42f6a8e8669350730270f5a91d64b6c70328b0156d75"

Response:

{
  "memberships": [
    {
      "id": 1,
      "site_id": 1,
      "user_id": 1,
      "balance": "10000.0",
      "created_at": "2015-08-04T00:21:34.623Z",
      "updated_at": "2015-08-04T00:21:34.651Z",
      "level": 1,
      "avatar": "ident/default_avatars/level-1-1.png",
      "role": "admin",
      "user": {
        "id": 1,
        "email": "user@example.com",
        "created_at": "2015-08-04T00:21:34.524Z",
        "updated_at": "2015-08-07T00:33:33.969Z",
        "username": "superman",
        "first_name": "Clark",
        "last_name": "Kent",
        "facebook_url": "www.facebook.com/superman",
        "twitter_url": "www.twitter.com/superman",
        "linkedin_url": "www.linkedin.com/superman",
        "blog_url": "www.blog.com/superman",
        "last_pageview_at": "2015-08-07T00:33:33.967Z",
        "last_prediction_at": null,
        "description": "He's a superhero"
      }
    },
    {
      "id": 2,
      "site_id": 1,
      "user_id": 2,
      "balance": "5298.92",
      "created_at": "2015-08-04T00:21:34.948Z",
      "updated_at": "2015-08-04T00:21:37.438Z",
      "level": 0,
      "avatar": "ident/default_avatars/level-0-1.png",
      "role": "user",
      "user": {
        "id": 2,
        "email": "user2@example.com",
        "created_at": "2015-08-04T00:21:34.924Z",
        "updated_at": "2015-08-04T00:21:34.924Z",
        "username": "superman2",
        "first_name": "Clark",
        "last_name": "Kent 2",
        "facebook_url": "www.facebook.com/superman2",
        "twitter_url": "www.twitter.com/superman2",
        "linkedin_url": "www.linkedin.com/superman2",
        "blog_url": "www.blog.com/superman2",
        "last_pageview_at": null,
        "last_prediction_at": null,
        "description": "He's a superhero2"
      }
    }
  ]
}

HTTP Request

GET https://yoursite.cultivateforecasts.com/api/v1/memberships

Query Parameters

Parameter Default Description
page 0 Pagination page number
include_profile_question_responses false Passing “true” for this value will include profile questions and responses for each membership.
created_before none Returns only memberships created before the passed time. Time should be in iso8601 format (e.g. 2015-08-23T15:43:11-05:00)
created_after none Returns only memberships created after the passed time. Time should be in iso8601 format (e.g. 2015-08-23T15:43:11-05:00)
update_before none Returns only memberships update before the passed time. Time should be in iso8601 format (e.g. 2015-08-23T15:43:11-05:00)
update_after none Returns only memberships update after the passed time. Time should be in iso8601 format (e.g. 2015-08-23T15:43:11-05:00)

Attribute Descriptions

Parameter Type Description
id integer The id of the membership
site_id integer The id of the site that this membership belongs to
user_id integer The id of the user that this membership belongs to
balance float The prediction market currency balance of the membership
level integer The user’s level. Only applicable in sites that use the user leveling system.
avatar_url string A URL containing an avatar image for the user
role string The role/privileges of the membership. Can be “user” or “admin”
user.id integer The id of the user
user.email string The email of the user
user.username string The username of the user
user.first_name string The first name of the user
user.last_name string The last name of the user
user.facebook_url string The url of the facebook profile of the user
user.twitter_url string The url of the twitter profile of the user
user.linkedin_url string The url of the linkedin profile of the user
user.blog_url string The url of the blog of the user
user.last_pageview_at date The timestamp of the user’s last pageview
user.last_prediction_at date The timestamp of the user’s last forecast
user.description string The user’s self-inputted description

Prediction Sets

A prediction set is the primary model for storing forecasts within Cultivate Forecasts. A prediction set can contain a single prediction or multiple predictions, depending on the question type. In a prediction market, all prediction sets have a single prediction (a trade). In an opinion pool, prediction sets have one prediction for each answer in the question.

Prediction Sets List

Request:

curl "https://yoursite.cultivateforecasts.com/api/v1/prediction_sets" \
  -H "Authorization: Bearer b95b4f848cd226e55b7a42f6a8e8669350730270f5a91d64b6c70328b0156d75"

Response:

{
  "prediction_sets": [
    {
      "id": 1,
      "membership_id": 2,
      "question_id": 1,
      "created_at": "2015-08-04T00:21:37.141Z",
      "updated_at": "2015-08-04T00:21:37.141Z",
      "comment_id": 123,
      "rationale": "0 - http://www.flyoverworks.com I live in the American Gardens Building on W. 81st Street on the 11th floor. My name is Patrick Bateman. I'm 27 years old. I believe in taking care of myself and a balanced diet and rigorous exercise routine. In the morning if my face is a little puffy I'll put on an ice pack while doing stomach crunches.",
      "predictions": [
        {
          "id": 1,
          "type": "Forecast::PM::LMSR::Trade",
          "answer_id": 1,
          "membership_id": 2,
          "paid": "2517.6",
          "quantity": 69,
          "forecasted_probability": "0.5",
          "starting_probability": "0.3333",
          "final_probability": "0.5",
          "filled_at": null,
          "refunded_at": null,
          "created_at": "2015-08-04T00:21:36.913Z",
          "updated_at": "2015-08-04T00:21:37.147Z",
          "confidence_level": "confidence_medium",
          "made_after_correctness_known": false
        }
      ]
    },
    {
      "id": 50,
      "membership_id": 5,
      "question_id": 2,
      "created_at": "2015-08-04T00:21:40.730Z",
      "updated_at": "2015-08-04T00:21:40.730Z",
      "comment_id": 123,
      "rationale": "7 -  Well, we have to end apartheid for one. And slow down the nuclear arms race, stop terrorism and world hunger. We have to provide food and shelter for the homeless, and oppose racial discrimination and promote civil rights, while also promoting equal rights for women.",
      "predictions": [
        {
          "id": 64,
          "type": null,
          "answer_id": 4,
          "membership_id": 5,
          "paid": null,
          "quantity": null,
          "forecasted_probability": "0.3333",
          "starting_probability": "0.3333",
          "final_probability": "0.3333",
          "filled_at": null,
          "refunded_at": null,
          "created_at": "2015-08-04T00:21:40.733Z",
          "updated_at": "2015-08-04T00:21:40.733Z",
          "confidence_level": null,
          "made_after_correctness_known": false
        },
        {
          "id": 65,
          "type": null,
          "answer_id": 5,
          "membership_id": 5,
          "paid": null,
          "quantity": null,
          "forecasted_probability": "0.3333",
          "starting_probability": "0.3333",
          "final_probability": "0.3333",
          "filled_at": null,
          "refunded_at": null,
          "created_at": "2015-08-04T00:21:40.741Z",
          "updated_at": "2015-08-04T00:21:40.741Z",
          "confidence_level": null,
          "made_after_correctness_known": false
        },
        {
          "id": 66,
          "type": null,
          "answer_id": 6,
          "membership_id": 5,
          "paid": null,
          "quantity": null,
          "forecasted_probability": "0.3333",
          "starting_probability": "0.3333",
          "final_probability": "0.3333",
          "filled_at": null,
          "refunded_at": null,
          "created_at": "2015-08-04T00:21:40.754Z",
          "updated_at": "2015-08-04T00:21:40.754Z",
          "confidence_level": null,
          "made_after_correctness_known": false
        }
      ]
    }
  ]
}

HTTP Request

GET https://yoursite.cultivateforecasts.com/api/v1/prediction_sets

Query Parameters

Parameter Default Description
page 0 Pagination page number
membership_id none Returns predictions for a single membership
question_id none Returns predictions for a single question
filter none Filters the question list. Possible values: comments_with_links, comments_following
created_before none Returns only prediction sets created before the passed date. Date should be in iso8601 format (e.g. 2015-08-23T15:43:11-05:00)
created_after none Returns only prediction sets created after the passed date. Date should be in iso8601 format (e.g. 2015-08-23T15:43:11-05:00)
updated_before none Returns only prediction sets updated before the passed date. Date should be in iso8601 format (e.g. 2015-08-23T15:43:11-05:00)
updated_after none Returns only prediction sets updated after the passed date. Date should be in iso8601 format (e.g. 2015-08-23T15:43:11-05:00)

Attribute Descriptions

Parameter Type Description
id integer The id of the prediction set
membership_id integer The id of the membership that submitted the prediction set
question_id integer The id of the question that this prediction set belongs to
rationale string The text of the rationale (if any) that the user submitted with the forecast
predictions.id integer The id of the prediction
predictions.answer_id integer The id of the answer this prediction belongs to
predictions.membership_id integer The id of the membership that submitted the prediction
predictions.filled_at date The timestamp of when the prediction was processed. This timestamp is used for scoring
predictions.refunded_at date The timestamp of when the prediction was refunded, if it’s a prediction market that has been refunded
predictions.made_after_correctness_known boolean Whether or not the prediction was submitted after the “correctness” of the answer was already known
predictions.spend float The amount of clinkles the user spent on the trade, if it’s in a prediction market
predictions.quantity float The number of shares the user received in the trade, if it’s in a prediction market
predictions.forecasted_probability float The probability estimate that the user submitted with the forecast
predictions.starting_probability float The consensus probability of the answer prior to incorporating this forecast
predictions.final_probability float The consensus probability of the answer prior to incorporating this forecast
predictions.starting_price float The price of the answer prior to incorporating this forecast (only applicable to prediction markets)
predictions.final_price float The price of the answer prior to incorporating this forecast (only applicable to prediction markets)

Prediction Set Creation

All predictions are part of a prediction set. In the case of a prediction market, the prediction set will have a single prediction (aka. a trade), while an opinion pool question will have multiple predictions as part of a single prediction set (one for each answer in the question).

This endpoint can be used to submit new prediction sets. All prediction sets require a question id as part of the URL and must include parameters for the prediction set. See below for a list of required parameters. All parameters must be nested under a “prediction_set” key (see example request body below).

Request:

curl -X "POST" "https://yoursite.cultivateforecasts.com/api/v1/questions/1/prediction_sets" \
  -H "Authorization: Bearer b95b4f848cd226e55b7a42f6a8e8669350730270f5a91d64b6c70328b0156d75" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
    -d "{\"prediction_set\":{\"rationale\":\"I think this is a great forecast\",\"predictions_attributes\":[{\"spend\":-595.9105910591059,\"forecasted_probability\":0.2,\"answer_id\":78}]}}"

Request body example:

{
  "prediction_set": {
    "rationale": "This is my rationale",
    "predictions_attributes": [
      {
        "spend": -595.91,
        "forecasted_probability": 0.2,
        "answer_id": 78
      }
    ]
  }
}

Response:

The response contains the newly created prediction set and associated prediction(s).

{
  "id": 16,
  "membership_id": 7,
  "membership_username": "superman7",
  "question_id": 36,
  "question_name": "lmsr_exclusive_market-8",
  "created_at": "2016-03-22T21:27:24.419Z",
  "updated_at": "2016-03-22T21:27:24.419Z",
  "rationale": "This is my rationale",
  "comment_id": 16,
  "predictions": [
    {
      "id": 16,
      "type": "Forecast::PM::LMSR::Trade",
      "answer_id": 78,
      "answer_name": "answer-name-78",
      "membership_id": 7,
      "filled_at": "2016-03-22T21:27:24.428Z",
      "refunded_at": null,
      "created_at": "2016-03-22T21:27:24.428Z",
      "updated_at": "2016-03-22T21:27:24.428Z",
      "confidence_level": null,
      "made_after_correctness_known": false,
      "spend": -595.91,
      "quantity": -8.6919,
      "forecasted_probability": 0.2,
      "starting_probability": 0.3333,
      "final_probability": 0.2,
      "starting_price": 0.3333,
      "final_price": 0.2959
    }
  ]
}

HTTP Request

POST https://yoursite.cultivateforecasts.com/api/v1/question/:question_id/prediction_sets

Prediction Set Parameters

Parameter Required? Description
rationale Configurable per site Contains the rationale/explanation/comment for why the user is making this forecast.
predictions_attributes Yes An array of prediction objects that are part of this prediction set. Valid parameters for a prediction are listed below.

Prediction Parameters

Parameter Required? Description
answer_id Yes The answer id on which the user is forecasting.
forecasted_probability Yes The probability assigned to this answer by the user. Should be a float between 0 and 1.
spend Only if the question is a prediction market The amount of clinkles to buy/sell as part of this prediction/trade. A positive value indicates a buy, while a negative value indicates a sell/short.

Positions

Positions List

This API returns a list of a user’s positions. This API is only accessible for the positions owned by the user who owns the oauth token that is included.

Each position record contains information about the most recent forecast made by the user in a given answer. It also includes information about any accumulated shares in prediction market-type questions.

Request:

curl "https://yoursite.cultivateforecasts.com/api/v1/positions" \
  -H "Authorization: Bearer b95b4f848cd226e55b7a42f6a8e8669350730270f5a91d64b6c70328b0156d75"

Response:

{
  "positions": [
    {
      "id": 32,
      "answer_name": "answer-name-4",
      "answer_id": 248,
      "created_at": "2017-01-17T20:07:30.360Z",
      "membership_id": 245,
      "question_name": "question-name-2",
      "question_id": 198,
      "resolved_at": null,
      "type": "Forecast::PM::Position",
      "last_prediction_at": "2017-01-10T20:07:30.347Z",
      "updated_at": "2017-01-17T20:07:30.360Z",
      "answer_current_consensus": 0.3333,
      "consensus_at_time_of_last_prediction": 0,
      "gain_loss_cache": 0,
      "latest_prediction_probability": 0,
      "liquidation_value_cache": 0,
      "long_investment": 0,
      "long_quantity": 0,
      "short_investment": 0,
      "short_quantity": 0,
      "net_quantity": 0
    },
    {
      "id": 33,
      "answer_name": "answer-name-6",
      "answer_id": 250,
      "created_at": "2017-01-17T20:07:30.365Z",
      "membership_id": 245,
      "question_name": "question-name-2",
      "question_id": 198,
      "resolved_at": null,
      "type": "Forecast::PM::Position",
      "last_prediction_at": "2017-01-03T20:07:30.363Z",
      "updated_at": "2017-01-17T20:07:30.365Z",
      "answer_current_consensus": 0.3333,
      "consensus_at_time_of_last_prediction": 0,
      "gain_loss_cache": 0,
      "latest_prediction_probability": 0,
      "liquidation_value_cache": 0,
      "long_investment": 0,
      "long_quantity": 0,
      "short_investment": 0,
      "short_quantity": 0,
      "net_quantity": 0
    },
    {
      "id": 31,
      "answer_name": "answer-name-1",
      "answer_id": 245,
      "created_at": "2017-01-17T20:07:30.137Z",
      "membership_id": 245,
      "question_name": "question-name-1",
      "question_id": 197,
      "resolved_at": null,
      "type": null,
      "last_prediction_at": "2016-12-17T20:07:30.116Z",
      "updated_at": "2017-01-17T20:07:30.137Z",
      "answer_current_consensus": 0.333333333,
      "consensus_at_time_of_last_prediction": 0,
      "gain_loss_cache": 0,
      "latest_prediction_probability": 0,
      "liquidation_value_cache": 0,
      "long_investment": 0,
      "long_quantity": 0,
      "short_investment": 0,
      "short_quantity": 0
    }
  ]
}

HTTP Request

GET https://yoursite.cultivateforecasts.com/api/v1/positions

Query Parameters

Parameter Default Description
page 0 Pagination page number
sort none The order in which to sort the positions. Valid values include question_name answer_name, answer_current_price, quantity, total_investment, gain_loss, liquidation_value, answer_last_prediction. By default, positions are sorted with most recently updated forecasts first.
dir “desc” The sort direction to apply to the sort filter. Valid values include asc and desc
filter none A filter to apply to the positions list. Valid values include closed (positions in closed/ended questions) and resolved (positions in resolved questions). If no filter is passed, only positions in active answers will be included.

Attribute Descriptions

Parameter Type Description
id integer The id of the position
answer_id integer The id of the answer associated with this position
membership_id integer The id of the membership that holds the position
question_id integer The id of the question associated with this position
resolved_at date The timestamp when this position was resolved (ie. paid out for a prediction market position). Empty if it hasn’t been resolved yet.
last_prediction_at date The timestamp of the last prediction that contributed to this position
answer_current_consensus float The current consensus probability of the answer that this position is in
consensus_at_time_of_last_prediction float The consensus probability of the answer at the time of the user’s last prediction in this answer
gain_loss_cache float The most recently calculated value for the gain/loss of this position (only applicable to prediction market positions)
latest_prediction_probability float The probability estimate of the user’s most recent prediction in this answer
liquidation_value_cache float The most recently calculated liquidation value for this position (only applicable to prediction market positions)
long_investment float The number of clinkles the user has spent on long trades in this answer (only applicable to prediction market positions)
long_quantity float The number of shares the user has accumulated from long trades in this answer (only applicable to prediction market positions)
short_investment float The number of clinkles the user has spent on short trades in this answer (only applicable to prediction market positions)
short_quantity float The number of shares the user has accumulated from short trades in this answer (only applicable to prediction market positions)

Questions

Questions List

Request:

curl "https://yoursite.cultivateforecasts.com/api/v1/questions" \
  -H "Authorization: Bearer b95b4f848cd226e55b7a42f6a8e8669350730270f5a91d64b6c70328b0156d75"

Response:

{
  "questions": [
    {
      "id": 5,
      "discover_question_id": 123,
      "name": "question-2",
      "type": "Forecast::Question",
      "site_id": 1,
      "membership_id": 1,
      "ends_at": "2015-09-15T00:21:35.906Z",
      "description": "question-desc-5",
      "published_at": null,
      "starts_at": null,
      "resolved_at": "2015-09-15T00:21:35.906Z",
      "voided_at": null,
      "predictions_count": 0,
      "comments_count": 0,
      "created_at": "2015-08-04T00:21:35.910Z",
      "updated_at": "2015-08-04T00:21:35.910Z",
      "scoring_start_time": "2015-09-15T00:21:35.906Z",
      "scoring_end_time": "2015-09-15T00:21:35.906Z",
      "state": "resolved",
      "active?": false,
      "resolved?": true,
      "resolution_notes": [
        "This question was resolved based on the ABC data source."
      ],
      "use_ordinal_scoring": false,
      "answers": [
        {
          "created_at": "2015-08-04T00:21:35.918Z",
          "ends_at": "2016-02-04T00:21:35.916Z",
          "id": 11,
          "discover_answer_id": 423,
          "membership_id": 1,
          "name": "answer-name-11",
          "outstanding": 0,
          "positions_count": null,
          "predictions_count": 0,
          "probability": "0.3333",
          "probability_formatted": "33.33%",
          "question_id": 5,
          "refunded_at": null,
          "refunded_by_id": null,
          "resolved_at": "2015-09-15T00:21:35.906Z",
          "resolved_by_id": 12,
          "correctness_known_at": "2015-09-15T00:21:35.906Z",
          "type": null,
          "updated_at": "2015-08-04T00:21:35.918Z"
        },
        {
          "created_at": "2015-08-04T00:21:35.927Z",
          "ends_at": "2016-02-04T00:21:35.925Z",
          "id": 12,
          "discover_answer_id": 424,
          "membership_id": 1,
          "name": "answer-name-12",
          "outstanding": 0,
          "positions_count": null,
          "predictions_count": 0,
          "probability": "0.3333",
          "probability_formatted": "33.33%",
          "question_id": 5,
          "refunded_at": null,
          "refunded_by_id": null,
          "resolved_at": "2015-09-15T00:21:35.906Z",
          "resolved_by_id": 12,
          "correctness_known_at": "2015-09-15T00:21:35.906Z",
          "type": null,
          "updated_at": "2015-08-04T00:21:35.927Z"
        },
        {
          "created_at": "2015-08-04T00:21:35.933Z",
          "ends_at": "2016-02-04T00:21:35.931Z",
          "id": 13,
          "discover_answer_id": 425,
          "membership_id": 1,
          "name": "answer-name-13",
          "outstanding": 0,
          "positions_count": null,
          "predictions_count": 0,
          "probability": "0.3333",
          "probability_formatted": "33.33%",
          "question_id": 5,
          "refunded_at": null,
          "refunded_by_id": null,
          "resolved_at": "2015-09-15T00:21:35.906Z",
          "resolved_by_id": 12,
          "correctness_known_at": "2015-09-15T00:21:35.906Z",
          "type": null,
          "updated_at": "2015-08-04T00:21:35.933Z"
        }
      ],
      "clarifications":[{
        "id":4,
        "question_id":5,
        "content":"clarification-content-1",
        "created_at":"2018-01-15T21:45:32.495Z",
        "updated_at":"2018-01-15T21:45:32.495Z"
      }]
    },
    {
      "id": 6,
      "discover_question_id": 31,
      "name": "binary_question-2",
      "type": "Forecast::Binary::Question",
      "site_id": 1,
      "membership_id": 1,
      "ends_at": "2015-09-15T00:21:35.945Z",
      "description": "question-desc-6",
      "published_at": null,
      "starts_at": null,
      "resolved_at": null,
      "voided_at": null,
      "predictions_count": 0,
      "comments_count": 0,
      "created_at": "2015-08-04T00:21:35.953Z",
      "updated_at": "2015-08-04T00:21:35.953Z",
      "scoring_start_time": "2015-09-15T00:21:35.906Z",
      "scoring_end_time": null,
      "state": "pending",
      "active?": true,
      "resolved?": false,
      "use_ordinal_scoring": false,
      "answers": [
        {
          "created_at": "2015-08-04T00:21:35.965Z",
          "ends_at": "2016-02-04T00:21:35.962Z",
          "id": 14,
          "discover_answer_id": 429,
          "membership_id": 1,
          "name": "answer-name-14",
          "outstanding": 0,
          "positions_count": null,
          "predictions_count": 0,
          "probability": "0.5",
          "probability_formatted": "50.00%",
          "question_id": 6,
          "refunded_at": null,
          "refunded_by_id": null,
          "resolved_at": null,
          "resolved_by_id": null,
          "correctness_known_at": null,
          "type": "Forecast::Binary::Answer",
          "updated_at": "2015-08-04T00:21:35.965Z"
        }
      ]
    }
  ]
}

HTTP Request

GET https://yoursite.cultivateforecasts.com/api/v1/questions

Query Parameters

Parameter Default Description
page 0 Pagination page number
tags none A comma separated list of tags to filter by (e.g. “sports,politics,tech”)
challenges none A comma separated list of challenge ids to filter by (e.g. “1,5,8”). Will return only questions in those challenges. Operates as a logical AND (ie. if you pass “1,5”, it will return only questions that are in both challenges)
filter none A filter to apply to the question list. Possible values: starred, featured. By default, no filter is applied.
status active A question status filter to apply to the question list. Possible values: closed, all. If this value is omitted, only active questions are returned. To include all questions, you should pass all for this value.
sort published_at Sort order for the questions. Possible values: published_at, ends_at, resolved_at, prediction_sets_count
created_before none Returns only questions created before the passed date. Date should be in iso8601 format (e.g. 2015-08-23T15:43:11-05:00)
created_after none Returns only questions created after the passed date. Date should be in iso8601 format (e.g. 2015-08-23T15:43:11-05:00)
updated_before none Returns only questions updated before the passed date. Date should be in iso8601 format (e.g. 2015-08-23T15:43:11-05:00)
updated_after none Returns only questions updated after the passed date. Date should be in iso8601 format (e.g. 2015-08-23T15:43:11-05:00)
include_tag_ids false Passing “true” for this value will include an array of tag ids for the question.
include_challenge_ids false Passing “true” for this value will include an array of challenge ids for the question.

Question Attributes

Parameter Type Description
id integer The id of the question
discover_question_id integer The id of the discover question used to generate/publish this question, if collaborative question generation (Discover) is being used
name string The question content
type string The internal question type (e.g. prediction market, binary prediction market, opinion pool)
site_id integer The id of the site that this question belongs to
membership_id integer The id of the membership who created this question
ends_at datetime The date & time that this question stops accepting forecasts
description string The description & background information for the question
published_at datetime The date & time that this question was published
starts_at datetime The date & time that this question started accepting forecasts
resolved_at datetime The date & time that this question was resolved
voided_at datetime The date & time that this question was voided. Blank if the question has not been voided. A voided question will not be resolved or scored.
predictions_count integer The number of predictions that have been made in this question
comments_count integer The number of comments that have been made in this question
created_at datetime The date & time that this question was created
updated_at datetime The date & time that this question was last updated
active boolean Whether or not this question is currently active for forecasting
resolved boolean Whether or not this question has been resolved
resolution_notes array Any notes/information provided by an admin describing the resolution of the question and any data sources used.
use_ordinal_scoring boolean Whether or not this question uses ordinal scoring for calculating Brier scores
clarifications array An array of clarifications issued for the question. Used to clarify things like resolution criteria for the question.
state string The current state of the question. Options include: active, ended, pending, refunded, resolved, voided
scoring_start_time datetime The time at which scoring starts for this question.
scoring_end_time datetime The time at which scoring ends for this question.

Answer Attributes

Parameter Type Description
id integer The id of the answer
discover_answer_id integer The id of the discover answer used to generate/publish this question, if collaborative question generation (Discover) is being used
created_at datetime The date & time that this answer was created
updated_at datetime The date & time that this answer was last updated
ends_at datetime The date & time that this answer stops accepting forecasts
membership_id integer The id of the membership who created this answer
name string The answer content
outstanding integer If this question is a prediction market, this represents the number of outstanding shares in this stock
positions_count integer The number of positions forecasters have taken in this answer
predictions_count integer The number of predictions forecasters have made in this answer
probability float The current consensus probability for this answer
probability_formatted string The current consensus probability for this answer, formatted as a percentage
question_id integer The id of the question that this answer belongs to
refunded_at datetime If this question is a prediction market and this stock has been refunded, the date & time the refund occurred
refunded_by_id integer The membership_id of the membership who refunded this stock
resolved_at datetime The date & time that this answer was resolved
resolved_by_id integer The memebership_id of the membership who resolved this answer
correctness_known_at datetime The date & time that the correctness of this answer was known. If an administrator sets this value when resolving the answer, all forecasts made after it will be invalidated.
type string The internal answer type (e.g. prediction market stock, opinion pool answer)

Questions Creation and Updating

HTTP Request:

POST https://yoursite.cultivateforecasts.com/api/v1/questions PATCH https://yoursite.cultivateforecasts.com/api/v1/questions/:id

Request body example:

{
  "question": {
    "name": "How many tournaments will Tiger win this year?",
    "description": "This question includes only major tournaments"
    "ends_at": "2017-12-31T23:59:59Z"
    "type": "Forecast::PM::LMSR::ExclusiveMarket"
    "answers_attributes": {
      "1": {
        "name": "0",
        "probability_whole_number": 47.5
      },
      "2": {
        "name": "1-5",
        "probability_whole_number": 22.5
      },
      "3": {
        "name": "6 or more",
        "probability_whole_number": 30
      }
    }
  }
}

Question Parameters

Parameter Required? Description
name Yes The name of the question
description Yes Background information, displays below the question name
links_attributes No An array of links to display below the question name. Valid parameters for links are listed below.
starts_at No The time at which the question begins accepting forecasts
ends_at Yes The time at which the question stops accepting forecasts
type Yes Valid question types are listed below – note that some question types are disabled on some sites
intro No An introduction that appears before the question name. eg “Sponsor XYZ presents:”
use_ordinal_scoring No An optional scoring setting for questions with sequential answers
rolling_range_count No For rolling questions, the number of answers active at a given time
rolling_time_length No For rolling questions, the number of time units allotted to each answer (eg 2 for two weeks, 4 for four years)
rolling_time_unit No For rolling questions, the unit of time for each answer. Options: “day”, “week”, “month”, “year”
roll_percentage No For rolling questions, the percentage of the probability assigned to the last bucket (eg 2020 or later) that will be transfered to the newly created bucket (2021 or later). The remainder will be assigned to the second last bucket (2020)
tag_list No An array containing the names of tags to be assigned to this question
challenge_ids No An array containing ids of challenges to be assigned to this question
answers_attributes Yes A hash of answer objects that are part of this question. Valid parameters for answers are listed below.
suspended No If selected, the question is suspended and does not accept new forecasts

Answer Parameters

Parameter Required? Description
name Yes The name of the answer
probability_whole_number Yes The starting probability of the answer
sort_order No The order in which this answer is displayed
id No The unique id of the answer–use only for updating
discover_answer_id No For questions created via Discover, the id of the Discover answer that corresponds to this answer
_destroy No Set to “true” to destroy this answer
Parameter Description
id The unique id of the link–use only for updating
url The url address of this link
description The text that displays for this link
_destroy Set to “true” to destroy this link

Question Types

Question Type Description
“Forecast::Question” A multi-answer prediction pool
“Forecast::Binary::Question” A prediction pool with only one answer (eg Yes/No)
“Forecast::RollingQuestion” A rolling prediction pool, with new answers appearing over time
“Forecast::PM::LMSR::ExclusiveMarket” A multi-answer prediction market with one correct answer
“Forecast::PM::LMSR::NonExclusiveMarket” A multi-answer prediction market that allows multiple correct answers
“Forecast::PM::LMSR::BinaryMarket” A prediction market with only one answer
“Forecast::PM::LMSR::RollingMarket” A rolling prediction market, with new answers appearing over time

Scores

Scores List

This API returns a list of score records. There are four types of score records: AnswerBrierScore, QuestionBrierScore, ChallengeBrierScore, and SiteBrierScore.

If a given record has a membership_id value, that indicates that it is a score for a specific membership. If the membership_id is null, that indicates that it represents the site-wide score. For example, a if a score with type Forecast::QuestionBrierScore has a null membership_id, that record is the site-wide consensus’ score for that particular question.

Request:

curl "https://yoursite.cultivateforecasts.com/api/v1/scores" \
  -H "Authorization: Bearer b95b4f848cd226e55b7a42f6a8e8669350730270f5a91d64b6c70328b0156d75"

Response:

{
  "scores": [
    {
      "id": 6207,
      "type": "Forecast::AnswerBrierScore",
      "value": "0.25",
      "scoreable_id": 4080,
      "scoreable_type": "Forecast::Answer",
      "site_id": 123,
      "membership_id": null,
      "period_started_at": null,
      "period_ended_at": null,
      "created_at": "2016-09-19T21:34:21.400Z",
      "updated_at": "2016-09-29T21:34:21.808Z",
      "ordinal_scoring_enabled": false,
      "use_price": false,
      "scoring_strategy_id": 484,
      "relative_brier_score": null,
      "median_brier_score_for_relative": null,
      "participation_rate": null,
      "prediction_made_by_id": null,
      "prediction_made_by_type": null
    },
    {
      "id": 6210,
      "type": "Forecast::QuestionBrierScore",
      "value": "0.25",
      "scoreable_id": 2554,
      "scoreable_type": "Forecast::Question",
      "site_id": 123,
      "membership_id": 8573,
      "period_started_at": null,
      "period_ended_at": null,
      "created_at": "2016-09-23T21:34:21.946Z",
      "updated_at": "2016-09-29T21:34:21.999Z",
      "ordinal_scoring_enabled": false,
      "use_price": false,
      "scoring_strategy_id": 484,
      "relative_brier_score": null,
      "median_brier_score_for_relative": null,
      "participation_rate": null,
      "prediction_made_by_id": null,
      "prediction_made_by_type": null
    },
    {
      "id": 6212,
      "type": "Forecast::ChallengeBrierScore",
      "value": "0.25",
      "scoreable_id": 406,
      "scoreable_type": "Forecast::Challenge",
      "site_id": 123,
      "membership_id": 8573,
      "period_started_at": null,
      "period_ended_at": null,
      "created_at": "2016-09-27T21:34:22.093Z",
      "updated_at": "2016-09-29T21:34:22.140Z",
      "ordinal_scoring_enabled": false,
      "use_price": false,
      "scoring_strategy_id": 484,
      "relative_brier_score": null,
      "median_brier_score_for_relative": null,
      "participation_rate": null,
      "prediction_made_by_id": null,
      "prediction_made_by_type": null
    },
    {
      "id": 6213,
      "type": "Forecast::SiteBrierScore",
      "value": "0.25",
      "scoreable_id": 5036,
      "scoreable_type": "Ident::Site",
      "site_id": 5035,
      "membership_id": null,
      "period_started_at": null,
      "period_ended_at": null,
      "created_at": "2016-09-28T21:34:22.143Z",
      "updated_at": "2016-09-29T21:34:22.187Z",
      "ordinal_scoring_enabled": false,
      "use_price": false,
      "scoring_strategy_id": 484,
      "relative_brier_score": null,
      "median_brier_score_for_relative": null,
      "participation_rate": null,
      "prediction_made_by_id": null,
      "prediction_made_by_type": null
    }
  ]
}

HTTP Request

GET https://yoursite.cultivateforecasts.com/api/v1/scores

Query Parameters

Parameter Default Description
page 0 Pagination page number
score_type none Returns scores of a specific type. Possible values: component (aka daily scores), answer, question, challenge, site
with_membership_id none If the value of this parameter is true, only scores with a membership_id set will be returned
without_membership_id none If the value of this parameter is true, only scores without a membership_id set will be returned
scoreable_id none Filters scores to include only scores for a single scoreable. This can be the id of an answer, question, challenge, or site record. If a value is passed for this parameter, the score_type record must also be set. So if you wanted scores for just a single question, you would pass score_type=question&scoreable_id=123
created_before none Returns only scores created before the passed date. Date should be in iso8601 format (e.g. 2015-08-23T15:43:11-05:00)
created_after none Returns only scores created after the passed date. Date should be in iso8601 format (e.g. 2015-08-23T15:43:11-05:00)
updated_before none Returns only scores updated before the passed date. Date should be in iso8601 format (e.g. 2015-08-23T15:43:11-05:00)
updated_after none Returns only scores updated after the passed date. Date should be in iso8601 format (e.g. 2015-08-23T15:43:11-05:00)

Attribute Descriptions

Parameter Type Description
id integer The id of the score
type string The type of score
value float The actual score value
scoreable_id integer The id of the record receiving the score. A “scoreable” is something that can receive a score in the system. This can be a membership, answer, question, challenge, or site. Combine with scoreable_type to determine the record receiving the score.
scoreable_type string The type of record receiving the score
period_started_at date The start date of the time period being scored
period_ended_at date The end date of the time period being scored
ordinal_scoring_enabled boolean Ordinal scoring can be enabled for questions where certain answers are “closer” to being correct than others (e.g. when the answers are buckets of numbers). This flag indicates whether ordinal scoring was enabled for this score.
use_price boolean A true value indicates that the stock price was used to generate this score (only applicable to prediction markets)
scoring_strategy_id integer A scoring strategy defines a set of settings used for scoring forecasts. This indicates the id of the strategy used to generate this score
relative_brier_score float The relative brier score
median_brier_score_for_relative float The median brier score for all forecasters in this answer+period combination, which is used to compute a relative brier score
participation_rate float The percentage of the days that the question ran in which the user was participating
prediction_made_by_id integer The id of the record that submitted the forecast that generated this score. Typically a membership, but can also be a team or an external predictor
prediction_made_by_type type The type of the record that submitted the forecast that generated this score.
site_id integer The id of the site that generated the score.

Stars

Stars List

If the user issuing a request to this endpoint is not an administrator, then a membership_id is required.

Request:

curl "https://yoursite.cultivateforecasts.com/api/v1/stars" \
  -H "Authorization: Bearer b95b4f848cd226e55b7a42f6a8e8669350730270f5a91d64b6c70328b0156d75"

Response:

{
  "stars": [
    {
      "id": 1,
      "membership_id": 1,
      "starrable_id": 6,
      "starrable_type": "Forecast::Question",
      "created_at": "2015-08-07T16:49:27.682Z",
      "updated_at": "2015-08-07T16:49:27.682Z"
    },
    {
      "id": 2,
      "membership_id": 1,
      "starrable_id": 5,
      "starrable_type": "Ident::Membership",
      "created_at": "2015-08-07T16:50:29.204Z",
      "updated_at": "2015-08-07T16:50:29.204Z"
    },
    {
      "id": 3,
      "membership_id": 1,
      "starrable_id": 1,
      "starrable_type": "Forecast::Challenge",
      "created_at": "2015-08-07T16:53:23.849Z",
      "updated_at": "2015-08-07T16:53:23.849Z"
    }
  ]
}

HTTP Request

GET https://yoursite.cultivateforecasts.com/api/v1/stars

Query Parameters

Parameter Default Description
page 0 Pagination page number
membership_id none Returns stars for a single membership id
filter none Filters the list of stars. Possible values: following, followers. To use a filter, a membership_id is required.

Users

Me

Each user can hit the “me” endpoint to get back information about him/herself and his/her memberships.

Request:

curl "https://yoursite.cultivateforecasts.com/api/v1/me" \
  -H "Authorization: Bearer b95b4f848cd226e55b7a42f6a8e8669350730270f5a91d64b6c70328b0156d75"

Response:

{
  "id": 1,
  "email": "user@example.com",
  "created_at": "2016-03-22T19:09:18.251Z",
  "updated_at": "2016-03-22T19:09:23.610Z",
  "username": "superman",
  "first_name": "Clark",
  "last_name": "Kent",
  "facebook_url": "http://www.facebook.com/superman",
  "twitter_url": "http://www.twitter.com/superman",
  "linkedin_url": "http://www.linkedin.com/superman",
  "blog_url": "http://www.blog.com/superman",
  "last_prediction_at": "2016-03-22T19:09:23.609Z",
  "description": "He's a superhero",
  "interface_mode": "simple_interface",
  "memberships": [
    {
      "id": 1,
      "site_id": 1,
      "user_id": 1,
      "created_at": "2016-03-22T19:09:18.397Z",
      "updated_at": "2016-03-22T19:09:22.386Z",
      "level": 1,
      "avatar": "ident/default_avatars/level-1-1.png",
      "last_pageview_at": "2016-03-22T19:09:18.336Z",
      "featured": false,
      "role": "admin",
      "balance": 14900,
      "available_balance": 14900,
      "max_spend": 1490,
      "avatar_url": "http://home.fof.dev:3000/assets/ident/default_avatars/level-1-1-761e8eeca490d58a1f87dcba4f594064e92c579857cb9a4f8e71bf4427eff3d0.png",
      "site": {
        "id": 1,
        "subdomain": "home",
        "name": "Site Name",
        "created_at": "2016-03-22T19:09:18.325Z",
        "updated_at": "2016-03-22T19:09:18.325Z",
        "avatar_style": "uses_level_avatars",
        "custom_domain": null,
        "allows_top_level_comments": true,
        "hides_empty_rationales_from_feed": false,
        "allows_interface_toggling": true,
        "clinkle_leaderboard_disabled": false,
        "brier_leaderboard_disabled": false,
        "mandatory_rationales": false
      }
    }
  ]
}

HTTP Request

GET https://yoursite.cultivateforecasts.com/api/v1/me

Query Parameters

None.

Creation

Use this endpoint to create new user accounts. Only certain users have permission to access this endpoint.

Request:

curl -X "POST" "https://yoursite.cultivateforecasts.com/api/v1/users/" \
  -H "Authorization: Bearer b95b4f848cd226e55b7a42f6a8e8669350730270f5a91d64b6c70328b0156d75" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d "{\"user\":{\"email\":\"slartibartfast@emaildomain.org\",\"username\":\"slartibartfast77\",\"password\":\"someamazingpassword\",\"first_name\":\"Slarti\",\"last_name\":\"bartfast\",\"description\":\"Indescribable\",\"interface_mode\":\"simple_interface\"}}"

Request body example:

{
  "user": {
    "email": "slartibartfast@emaildomain.org",
    "username": "slartibartfast77",
    "password": "slartibartfast77",
    "first_name": "Slarti",
    "last_name": "bartfast",
    "description": "Indescribable",
    "interface_mode": "simple_interface"
  }
}

HTTP Request

POST https://yoursite.cultivateforecasts.com/api/v1/users

User Parameters

Parameter Required? Description Requirements
email Yes The user’s email address Users must have unique email addresses
username Yes Usernames must be unique, and only allow letters, numbers, hyphens and underscores (no other characters)
password Yes Must be at least 8 characters long
first_name No
last_name No
description No
interface_mode No Determines which forecasting interface the user will see on the website Options are “simple_interface” and “advanced_interface”. “simple_interface” is selected by default.

Votes

Votes List

Provides a list of upvotes & downvotes. Votes with a value of 1 are upvotes and votes with a value of -1 are downvotes.

This endpoint is only accessible to site administrators.

Request:

curl "https://yoursite.cultivateforecasts.com/api/v1/votes" \
  -H "Authorization: Bearer b95b4f848cd226e55b7a42f6a8e8669350730270f5a91d64b6c70328b0156d75"

Response:

{
  "votes": [
    {
      "id": 1,
      "comment_id": 24,
      "ident_membership_id": 51,
      "value": 1,
      "created_at": "2015-11-09T17:14:13.229Z"
    },
    {
      "id": 2,
      "comment_id": 27,
      "ident_membership_id": 14,
      "value": -1,
      "created_at": "2015-11-09T19:22:41.984Z"
    }
  ]
}

HTTP Request

GET https://yoursite.cultivateforecasts.com/api/v1/votes

Query Parameters

Parameter Default Description
page 0 Pagination page number