NAV
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).

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

Comments

Comments List

Shows a list of comments that exist on the site.

Request:

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

Response:

{
    "comments": [
        {
            "id": 439,
            "commenter_type": "Ident::Membership",
            "content": "anonymous comment",
            "commentable_id": 563,
            "commentable_type": "Forecast::Question",
            "children_count": 0,
            "parent_id": null,
            "created_at": "2020-11-13T16:29:58.124Z",
            "updated_at": "2020-11-13T16:29:58.124Z",
            "anonymous": true,
            "commentable_name": "question-name-8"
        },
        {
            "id": 436,
            "commenter_type": "Ident::Membership",
            "content": "comment 2",
            "commentable_id": 563,
            "commentable_type": "Forecast::Question",
            "children_count": 0,
            "parent_id": null,
            "created_at": "2020-11-13T16:29:58.051Z",
            "updated_at": "2020-11-13T16:29:58.051Z",
            "anonymous": false,
            "membership_username": "TheTank17",
            "membership_avatar_url": "http://test-1.lvh.me/assets/default_theme/v18/ident/default_avatars/level-1-1-2585542198c786697ecae8838813bd0a558e8b40bee4f21676d05e014d3ccc52.png",
            "commenter_id": 1207,
            "commentable_name": "question-name-8"
        },
        {
            "id": 435,
            "commenter_type": "Ident::Membership",
            "content": "comment 1",
            "commentable_id": 563,
            "commentable_type": "Forecast::Question",
            "children_count": 1,
            "parent_id": null,
            "created_at": "2020-11-13T16:29:58.030Z",
            "updated_at": "2020-11-13T16:29:58.030Z",
            "anonymous": false,
            "membership_username": "TheTank16",
            "membership_avatar_url": "http://test-1.lvh.me/assets/default_theme/v18/ident/default_avatars/level-1-1-2585542198c786697ecae8838813bd0a558e8b40bee4f21676d05e014d3ccc52.png",
            "commenter_id": 1206,
            "commentable_name": "question-name-8"
        }
    ]
}

HTTP Request

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

Query Parameters

Parameter Default Description
page 0 Pagination page number
created_before none Returns only history records 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 history records 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 history records 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 history records updated after the passed date. Date should be in iso8601 format (e.g. 2015-08-23T15:43:11-05:00)
include_replies false Whether to include comment replies
commentable_id none The ID of the resource to scope the list of comments to. E.g. a question ID, if you want only comments from that question
commentable_type none If commentable_id is provided, this must be provided. Valid options: Forecast::Question, Ident::Site, and Cms::Post

Attribute Descriptions

Parameter Type Description
id integer The id of the comment
commenter_type string The type of resource that created the comment
content string The comment text
commentable_id integer The ID of the resource where this comment was made (e.g. a question or a blog post)
commentable_type string The type of resource where this comment was made (e.g. a question or a blog post)
commentable_name string The name of the resource where this comment was made (e.g. the question's text or blog post's title)
children_count integer The number of replies that have been made to this comment
parent_id integer If this was a reply, the ID of the comment it was replying to
created_at datetime The creation timestamp
updated_at datetime The timestamp of when this comment was last updated
anonymous boolean Whether this comment was made anonymously
membership_username string The username of the user who created the comment
membership_avatar_url string The URL of the user's avatar image
commenter_id integer The ID of the membership/user who made the comment

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 Badge Bulk Deletion

This endpoint allows you to delete all earned badge assignments for a given badge. Note that there may be a slight delay while the deletion processes if a large number of assignments are being deleted.

Request:

curl -X "POST" "https://yoursite.cultivateforecasts.com/api/v1/earned_badges/bulk_deletions?badge_id=123" \
  -H "Authorization: Bearer b95b4f848cd226e55b7a42f6a8e8669350730270f5a91d64b6c70328b0156d75" \
  -H "Accept: application/json"

HTTP Request

POST https://yoursite.cultivateforecasts.com/api/v1/earned_badges/bulk_deletions?badge_id=123

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
badge_id none Filter the list to only return records for a given badge

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,
      "created_at": "2015-08-04T00:21:34.623Z",
      "updated_at": "2015-08-04T00:21:34.651Z",
      "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,
      "created_at": "2015-08-04T00:21:34.948Z",
      "updated_at": "2015-08-04T00:21:37.438Z",
      "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
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 / Forecasts

A prediction set is the primary model for storing individual user forecasts within Cultivate Forecasts. Prediction sets have one prediction for each possible 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": 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,
          "forecasted_probability": "0.3333",
          "starting_probability": "0.3333",
          "final_probability": "0.3333",
          "filled_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,
          "forecasted_probability": "0.3333",
          "starting_probability": "0.3333",
          "final_probability": "0.3333",
          "filled_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,
          "forecasted_probability": "0.3333",
          "starting_probability": "0.3333",
          "final_probability": "0.3333",
          "filled_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.made_after_correctness_known boolean Whether or not the prediction was submitted after the "correctness" of the answer was already known
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

Prediction Set Creation

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\":\"An api prediction\",\"predictions_attributes\":[{,\"forecasted_probability\":0.42,\"answer_id\":140}]}}"

Request body example:

{
  "prediction_set": {
    "rationale": "An api prediction",
    "predictions_attributes": [
      {
        "forecasted_probability": 0.42,
        "answer_id": 140
      }
    ]
  }
}

Response:

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

{
    "id": 17,
    "type": "Forecast::OpinionPoolPredictionSet",
    "membership_id": 233,
    "membership_username": "TheTank38",
    "membership_avatar_url": "/assets/default_theme/v18/ident/default_avatars/level-1-1-b9c925ca8bbd1b06f41ec78eecb73e098a6f1dc741c688684307fa6d59917c69.png",
    "question_id": 56,
    "created_at": "2021-12-02T19:55:14.055Z",
    "updated_at": "2021-12-02T19:55:14.101Z",
    "question_name": "question-name 51ff26bb6cc0",
    "discover_question_id": 832,
    "rationale": "An api prediction",
    "comment_id": 21,
    "predictions": [
        {
            "id": 33,
            "type": "Forecast::Prediction",
            "answer_id": 140,
            "membership_id": 233,
            "created_at": "2021-12-02T19:55:14.063Z",
            "updated_at": "2021-12-02T19:55:14.099Z",
            "made_after_correctness_known": false,
            "forecasted_probability": 0.42,
            "starting_probability": 0.5,
            "final_probability": 0.42,
            "answer_name": "answer-name-29"
        }
    ],
    "question": {
        "active?": true,
        "state": "active",
        "binary?": true,
        "comments_count": 1,
        "correct_answer_became_highest_probability_answer_at": null,
        "correct_answer_became_highest_probability_days_before_close": null,
        "correct_answer_became_highest_probability_percentage_of_question": null,
        "closed_at": null,
        "created_at": "2021-12-02T19:55:13.987Z",
        "description": "question-desc ec45d76206ef",
        "discover_question_id": 832,
        "ends_at": "2021-12-09T19:55:00.000Z",
        "exclusive?": true,
        "external_source": null,
        "external_id": null,
        "featured": false,
        "id": 56,
        "image": null,
        "membership_id": 1019,
        "name": "question-name 51ff26bb6cc0",
        "number_bins": "disabled",
        "answers_count": 1,
        "post_forecast_survey_id": null,
        "prediction_sets_count": 1,
        "predictors_count": 1,
        "predictions_must_sum_to_100?": false,
        "published_at": "2021-12-02T19:55:12.984Z",
        "resolved_at": null,
        "resolved?": false,
        "resolution_notes": [],
        "site_id": 138,
        "starts_at": "2021-12-02T19:55:00.000Z",
        "type": "Forecast::Binary::Question",
        "updated_at": "2021-12-02T19:55:14.103Z",
        "use_ordinal_scoring": false,
        "voided_at": null,
        "void_reason": null,
        "metadata": {},
        "brier_score": "9.99",
        "scoring_start_time": "2021-12-02T14:55:12.984-05:00",
        "scoring_end_time": null,
        "answers": [
            {
                "id": 140,
                "discover_answer_id": null,
                "active?": true,
                "binary?": true,
                "correctness_known_at": null,
                "created_at": "2021-12-02T19:55:13.991Z",
                "description": "answer-desc-29",
                "display_probability": "42%",
                "ended?": false,
                "ends_at": null,
                "membership_id": 1019,
                "positions_count": 1,
                "predictions_count": 1,
                "probability_formatted": "42%",
                "question_id": 56,
                "question_name": "question-name 51ff26bb6cc0",
                "resolved_at": null,
                "resolved_by_id": null,
                "resolved?": false,
                "resolving?": false,
                "sort_order": 29,
                "status": null,
                "type": "Forecast::Binary::Answer",
                "updated_at": "2021-12-02T19:55:14.079Z",
                "name": "answer-name-29",
                "normalized_probability": 0.42,
                "probability": 0.42
            }
        ],
        "clarifications": []
    }
}

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.

Questions

Questions List

Request:

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

Response:

{
  "questions": [
    {
      "id": 5,
      "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,
      "post_forecast_survey_id": 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,
          "membership_id": 1,
          "name": "answer-name-11",
          "positions_count": null,
          "predictions_count": 0,
          "probability": "0.3333",
          "probability_formatted": "33.33%",
          "question_id": 5,
          "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,
          "membership_id": 1,
          "name": "answer-name-12",
          "positions_count": null,
          "predictions_count": 0,
          "probability": "0.3333",
          "probability_formatted": "33.33%",
          "question_id": 5,
          "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,
          "membership_id": 1,
          "name": "answer-name-13",
          "positions_count": null,
          "predictions_count": 0,
          "probability": "0.3333",
          "probability_formatted": "33.33%",
          "question_id": 5,
          "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,
      "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,
      "post_forecast_survey_id": 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,
          "membership_id": 1,
          "name": "answer-name-14",
          "positions_count": null,
          "predictions_count": 0,
          "probability": "0.5",
          "probability_formatted": "50.00%",
          "question_id": 6,
          "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
ids none A comma separated list of question ID's to return (e.g. "123,124,125")
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
active boolean Whether or not this question is currently active for forecasting
clarifications array An array of clarifications issued for the question. Used to clarify things like resolution criteria for the 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
description string The description & background information for the question
ends_at datetime The date & time that this question stops accepting forecasts
id integer The id of the question
membership_id integer The id of the membership who created this question
name string The question content
post_forecast_survey_id integer If a survey is administered after forecasts in this question, the ID of that survey
predictions_count integer The number of predictions that have been made in this question
published_at datetime The date & time that this question was published
resolution_notes array Any notes/information provided by an admin describing the resolution of the question and any data sources used.
resolved boolean Whether or not this question has been resolved
resolved_at datetime The date & time that this question was resolved
scoring_end_time datetime The time at which scoring ends for this question.
scoring_start_time datetime The time at which scoring starts for this question.
site_id integer The id of the site that this question belongs to
starts_at datetime The date & time that this question started accepting forecasts
state string The current state of the question. Options enumerated in question states
type string The internal question type
updated_at datetime The date & time that this question was last updated
use_ordinal_scoring boolean Whether or not this question uses ordinal scoring for calculating Brier scores
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.

Answer Attributes

Parameter Type Description
id integer The id of the answegenerate/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
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
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

Question States

State Description
active Currently open for forecasting
rejected An admin rejected the suggested question. It won't be published for forecasting.
voided The question was published for forecasting, but subsequently voided due to unforeseen issues with the question. It will not be scored or resolved.
resolved The question has ended, been judged, and scored (or is in the process of scoring).
pending An admin created the question, but has not yet published it.
pending_resolution The question's ends_at timestamp has passed, but it has not yet been resolved.

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::Question"
    "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 updatinthe 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)

Scores

Scores List

This API returns a list of score records. There are three types of score records: QuestionBrierScore (a score for a single question), ChallengeBrierScore (a score for all questions in a challenge), and SiteBrierScore (an overall score).

If a given record has a prediction_made_by_id value, that indicates that it is a score for a specific predictor. If the prediction_made_by_id is null, that indicates that it represents the crowd's score.

Request:

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

Response:

{
    "scores": [
        {
            "id": 10,
            "type": "Forecast::SiteBrierScore",
            "value": "0.25",
            "scoreable_id": 13,
            "scoreable_type": "Ident::Site",
            "site_id": 13,
            "period_started_at": null,
            "period_ended_at": null,
            "created_at": "2021-05-28T12:37:18.827Z",
            "updated_at": "2021-05-28T13:37:18.850Z",
            "ordinal_scoring_enabled": false,
            "scoring_strategy_id": 2,
            "relative_brier_score": null,
            "comparison_brier_score_for_relative": null,
            "participation_rate": null,
            "prediction_made_by_id": 3,
            "prediction_made_by_type": "Ident::Membership",
            "forecasted_probability": null,
            "forecast_type": null
        },
        {
            "id": 8,
            "type": "Forecast::ChallengeBrierScore",
            "value": "0.25",
            "scoreable_id": 2,
            "scoreable_type": "Forecast::Challenge",
            "site_id": 2,
            "period_started_at": null,
            "period_ended_at": null,
            "created_at": "2021-05-26T13:37:18.758Z",
            "updated_at": "2021-05-28T13:37:18.790Z",
            "ordinal_scoring_enabled": false,
            "scoring_strategy_id": 2,
            "relative_brier_score": null,
            "comparison_brier_score_for_relative": null,
            "participation_rate": null,
            "prediction_made_by_id": 3,
            "prediction_made_by_type": "Ident::Membership",
            "forecasted_probability": null,
            "forecast_type": null
        },
        {
            "id": 5,
            "type": "Forecast::QuestionBrierScore",
            "value": "0.25",
            "scoreable_id": 5,
            "scoreable_type": "Forecast::Question",
            "site_id": 2,
            "period_started_at": null,
            "period_ended_at": null,
            "created_at": "2021-05-26T13:37:18.578Z",
            "updated_at": "2021-05-28T13:37:18.679Z",
            "ordinal_scoring_enabled": false,
            "scoring_strategy_id": 2,
            "relative_brier_score": null,
            "comparison_brier_score_for_relative": null,
            "participation_rate": null,
            "prediction_made_by_id": 1,
            "prediction_made_by_type": "Aggregation::Method",
            "forecasted_probability": null,
            "forecast_type": null,
            "discover_question_id": 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: question, challenge, site
membership_id none If this ID is present, the endpoint will give back scores for only that membership/user
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 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
predictor_type none Filters scores to include only predicotrs of a certain type. Possible values: user, team
include_daily_scores false If true, a daily_scores attribute will be included with question scores that includes a breakdown of the predictor's daily scores for that question.
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.
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.

Surveys

Survey Detail

Shows a survey and its responses

Request:

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

Response:

{
  "id": 142,
  "name": "survey-2",
  "user_id": 660,
  "created_at": "2021-02-16T20:20:55.872Z",
  "updated_at": "2021-02-16T20:20:55.872Z",
  "published": false,
  "description": "survey-description-2",
  "instructions": "survey-instructions-2",
  "randomize_page_order": false,
  "survey_pages": [
    {
      "id": 283,
      "name": "survey-page-3",
      "survey_id": 142,
      "user_id": 1003,
      "page_number": 1,
      "created_at": "2021-02-16T20:20:55.878Z",
      "updated_at": "2021-02-16T20:20:55.878Z",
      "time_limit": null,
      "type": null,
      "content": null,
      "acceptance_checkbox_text": null,
      "randomize_question_order": false,
      "survey_questions": [
        {
          "id": 421,
          "name": "survey-question-name-5",
          "content": "question-content-5",
          "answer_type": "dropdown",
          "survey_page_id": 283,
          "created_at": "2021-02-16T20:20:55.885Z",
          "updated_at": "2021-02-16T20:20:55.885Z",
          "response_forcing": "force",
          "image_url": null,
          "survey_answers": [
            {
              "id": 607,
              "value": "answer-value-7",
              "survey_question_id": 421,
              "created_at": "2021-02-16T20:20:55.886Z",
              "updated_at": "2021-02-16T20:20:55.886Z",
              "image_url": null
            },
            {
              "id": 608,
              "value": "answer-value-8",
              "survey_question_id": 421,
              "created_at": "2021-02-16T20:20:55.888Z",
              "updated_at": "2021-02-16T20:20:55.888Z",
              "image_url": null
            }
          ]
        },
        {
          "id": 422,
          "name": "survey-question-name-6",
          "content": "question-content-6",
          "answer_type": "text",
          "survey_page_id": 283,
          "created_at": "2021-02-16T20:20:55.889Z",
          "updated_at": "2021-02-16T20:20:55.889Z",
          "response_forcing": "not_required",
          "image_url": null,
          "survey_answers": []
        }
      ]
    },
    {
      "id": 284,
      "name": "survey-page-4",
      "survey_id": 142,
      "user_id": 1004,
      "page_number": 2,
      "created_at": "2021-02-16T20:20:55.881Z",
      "updated_at": "2021-02-16T20:20:55.881Z",
      "time_limit": null,
      "type": null,
      "content": null,
      "acceptance_checkbox_text": null,
      "randomize_question_order": false,
      "survey_questions": [
        {
          "id": 423,
          "name": "survey-question-name-7",
          "content": "question-content-7",
          "answer_type": "radio",
          "survey_page_id": 284,
          "created_at": "2021-02-16T20:20:55.892Z",
          "updated_at": "2021-02-16T20:20:55.892Z",
          "response_forcing": "suggest",
          "image_url": null,
          "survey_answers": [
            {
              "id": 609,
              "value": "answer-value-9",
              "survey_question_id": 423,
              "created_at": "2021-02-16T20:20:55.894Z",
              "updated_at": "2021-02-16T20:20:55.894Z",
              "image_url": null
            },
            {
              "id": 610,
              "value": "answer-value-10",
              "survey_question_id": 423,
              "created_at": "2021-02-16T20:20:55.896Z",
              "updated_at": "2021-02-16T20:20:55.896Z",
              "image_url": null
            }
          ]
        },
        {
          "id": 424,
          "name": "survey-question-name-8",
          "content": "question-content-8",
          "answer_type": "numeric",
          "survey_page_id": 284,
          "created_at": "2021-02-16T20:20:55.898Z",
          "updated_at": "2021-02-16T20:20:55.898Z",
          "response_forcing": "not_required",
          "image_url": null,
          "survey_answers": [
            {
              "id": 611,
              "value": "answer-value-11",
              "survey_question_id": 424,
              "created_at": "2021-02-16T20:20:55.900Z",
              "updated_at": "2021-02-16T20:20:55.900Z",
              "image_url": null
            },
            {
              "id": 612,
              "value": "answer-value-12",
              "survey_question_id": 424,
              "created_at": "2021-02-16T20:20:55.902Z",
              "updated_at": "2021-02-16T20:20:55.902Z",
              "image_url": null
            }
          ]
        }
      ]
    }
  ],
  "survey_responses": [
    {
      "id": 235,
      "user_id": 658,
      "survey_id": 142,
      "question_id": 123,
      "created_at": "2021-02-16T20:20:55.903Z",
      "updated_at": "2021-02-16T20:20:55.903Z",
      "status": "completed",
      "page_order": [
        "283",
        "284"
      ],
      "survey_question_responses": [
        {
          "id": 562,
          "survey_question_id": 421,
          "survey_answer_id": 607,
          "survey_response_id": 235,
          "created_at": "2021-02-16T20:20:55.914Z",
          "updated_at": "2021-02-16T20:20:55.914Z",
          "question_content": "*question-content-5",
          "answer_content": "answer-value-7"
        },
        {
          "id": 563,
          "survey_question_id": 422,
          "survey_answer_id": null,
          "survey_response_id": 235,
          "created_at": "2021-02-16T20:20:55.916Z",
          "updated_at": "2021-02-16T20:20:55.916Z",
          "question_content": "question-content-6",
          "answer_content": "I am the one who knocks."
        },
        {
          "id": 564,
          "survey_question_id": 423,
          "survey_answer_id": 607,
          "survey_response_id": 235,
          "created_at": "2021-02-16T20:20:55.918Z",
          "updated_at": "2021-02-16T20:20:55.918Z",
          "question_content": "question-content-7",
          "answer_content": "answer-value-7"
        },
        {
          "id": 565,
          "survey_question_id": 424,
          "survey_answer_id": null,
          "survey_response_id": 235,
          "created_at": "2021-02-16T20:20:55.921Z",
          "updated_at": "2021-02-16T20:20:55.921Z",
          "question_content": "question-content-8",
          "answer_content": [
            611,
            612
          ]
        }
      ]
    }
  ]
}

HTTP Request

GET https://yoursite.cultivateforecasts.com/api/v1/surveys/:id

Query Parameters

Parameter Default Description
responses_page 0 Pagination page number for the list of survey responses

Attribute Descriptions

Parameter Type Description
id integer The id of the survey
site_id integer The id of the site this survey belongs to
name string The name of the survey
created_at datetime The creation timestamp for the survey
updated_at datetime The timestamp for the most recent update of this survey
published boolean Whether or not this survey has been published
description string The description of the survey
instructions string Instructions to be presented to the user at the start of the survey
randomize_page_order boolean Whether or not the pages in the survey will be presented to the user in random order

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",
  "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",
      "avatar": "ident/default_avatars/level-1-1.png",
      "last_pageview_at": "2016-03-22T19:09:18.336Z",
      "featured": false,
      "role": "admin",
      "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\"}}"

Request body example:

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

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

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