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 |
| 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 |
Comment Creation
Creates a comment. The comment will be attributed to the owner of the oauth token that you're using to submit the request. To reply to another comment, you should include a parent_id parameter containing the ID of the comment to which you're replying.
Request:
curl -X "POST" "https://yoursite.cultivateforecasts.com/api/v1/comments" \
-H "Authorization: Bearer b95b4f848cd226e55b7a42f6a8e8669350730270f5a91d64b6c70328b0156d75" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d "{\"parent_id\": 123, \"commentable_id\":959,\"commentable_type\":\"Forecast::Question\",\"comment\":{\"content\":\"And now his watch has ended.\"}}"
Request body example:
{
"commentable_id": 959,
"commentable_type": "Forecast::Question",
"comment": {
"content": "And now his watch has ended."
}
}
Response:
If the comment is not a reply, the response contains the newly created comment.
If the comment is a reply (ie. a parent_id was given), the response contains the parent comment and its children.
// When creating a non-reply comment:
{
"id": 1177,
"commentable_id": 959,
"commentable_type": "Forecast::Question",
"children_count": 0,
"parent_id": null,
"created_at": "2023-09-26T15:16:07.461Z",
"updated_at": "2023-09-26T15:16:07.461Z",
"net_votes_count": 0,
"anonymous": false,
"membership_username": "TheTank2",
"membership_avatar_url": "/assets/default_theme/v18/ident/default_avatars/level-1-1-b9c925ca8bbd1b06f41ec78eecb73e098a6f1dc741c688684307fa6d59917c69.png",
"commenter_id": 2265,
"commenter_type": "Ident::Membership",
"commentable_name": "question-name ff632fd942fc",
"content": "And now his watch has ended.",
"content_html": "\u003cdiv class=\"content\"\u003e\n \n\u003cdiv class=\"raw_content\"\u003e\n And now his watch has ended.\n\u003c/div\u003e\n\u003c/div\u003e"
}
// When creating a reply comment:
{
"id": 1195,
"commentable_id": 959,
"commentable_type": "Forecast::Question",
"children_count": 0,
"parent_id": null,
"created_at": "2023-09-26T15:57:22.074Z",
"updated_at": "2023-09-26T15:57:22.074Z",
"net_votes_count": 0,
"anonymous": false,
"membership_username": "TheTank4",
"membership_avatar_url": "/assets/default_theme/v18/ident/default_avatars/level-1-1-b9c925ca8bbd1b06f41ec78eecb73e098a6f1dc741c688684307fa6d59917c69.png",
"commenter_id": 2264,
"commenter_type": "Ident::Membership",
"commentable_name": "question-name d43b5b6bbbe0",
"content": "comment\n 1",
"content_html": "\u003cdiv class=\"content\"\u003e\n \n\u003cdiv class=\"raw_content\"\u003e\n \u003cbr\u003ecomment\u003cbr\u003e 1\n\u003c/div\u003e\n\u003c/div\u003e",
"children": [
{
"id": 1196,
"commentable_id": 959,
"commentable_type": "Forecast::Question",
"children_count": 0,
"parent_id": 123,
"created_at": "2023-09-26T15:57:22.113Z",
"updated_at": "2023-09-26T15:57:22.113Z",
"net_votes_count": 0,
"anonymous": false,
"membership_username": "TheTank2",
"membership_avatar_url": "/assets/default_theme/v18/ident/default_avatars/level-1-1-b9c925ca8bbd1b06f41ec78eecb73e098a6f1dc741c688684307fa6d59917c69.png",
"commenter_id": 2265,
"commenter_type": "Ident::Membership",
"content": "And now his watch has ended.",
"content_html": "\u003cdiv class=\"content\"\u003e\n \n\u003cdiv class=\"raw_content\"\u003e\n And now his watch has ended.\n\u003c/div\u003e\n\u003c/div\u003e"
}
]
}
HTTP Request
POST https://yoursite.cultivateforecasts.com/api/v1/comments
Comment Parameters
| Parameter | Required? | Description |
|---|---|---|
| parent_id | No | The ID of another comment to which this is a reply. |
| commentable_id | Yes | The ID of the commentable that this comment should be attached to. Most likely a question ID. |
| commentable_type | Yes | The type of commentable that this comment should be attached to. Most likely Forecast::Question. |
| comment.content | Yes | The text of 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 |
Link Parameters
| 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 |
|---|---|---|---|
| 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 |