Get all stories API

Owned by Matt Kepple
Last updated: Jan 02, 2024 by Chaitanya Varu
5 min read

You can use the API to

  • get all the stories that belong to a particular beneficiary.

  • get all the stories your user account has access to

API Documentation

  • Endpoint: GET /api/v2/stories?page=2&per_page=2

  • Authentication: Requires valid authentication token

  • Response format: JSON

  • Query Parameters:

    • page (integer, optional): The page number for pagination (default is 1).

    • per_page (integer, optional): The number of choices per page (default is 10).

Response Attributes

  • page (integer): The current page number.

  • page_size (integer): The number of choices per page.

  • page_count (integer): The total number of pages.

  • total_count (integer): The total number of stories.

  • data (array of objects): List of stories.

    • id (integer): The unique identifier for the story.

    • text (string, nullable): The text content of the story.

    • number (string): The story number.

    • approved (boolean): Indicates if the story is approved.

    • story_group (string): The story group to which the story belongs.

    • location (string, nullable): The location associated with the story.

    • project_id (integer): The identifier of the associated project.

    • charity_id (integer, nullable): The identifier of the associated charity.

    • story_category_id (integer): The identifier of the story category.

    • edited_by (integer): The user ID who edited the story.

    • user_id (integer): The user ID who created the story.

    • updated_at (string): The timestamp of the last update.

    • created_at (string): The timestamp of the creation.

    • actual_created_at (string): The actual timestamp of creation.

    • beneficiary_ids (array): An array of beneficiary IDs associated with the story.

    • custom_fields (array): An array of custom field objects.

      • id (integer): The unique identifier for the custom field.

      • name (string): The name of the custom field.

      • type (string): The type of the custom field (e.g., text).

      • value (string): The value of the custom field.

Example

GET https://makerble.com/api/v2/stories?page=22&per_page=2

Response

{ "page": 22, "page_size": 2, "page_count": 5890, "total_count": 11779, "data": [ { "id": 369011, "text": null, "number": "0", "approved": true, "story_group": "change_created", "location": null, "project_id": 3172, "charity_id": null, "story_category_id": 4255, "edited_by": 5656, "user_id": 5656, "updated_at": "2023-10-10T11:18:21.208+01:00", "created_at": "2023-10-10T11:18:20.000+01:00", "actual_created_at": "2023-10-10T11:18:20.278+01:00", "beneficiary_ids": [ 146776 ], "custom_fields": [ { "id": 3252, "name": "Interests and activities", "type": "text", "value": "" }, { "id": 3253, "name": "Hopes and dreams", "type": "text", "value": "" } ] }, { "id": 369010, "text": "I have a Spoken to Kitt About Attending The Great Birmingham Social, on the 18th October 2023. Kitt Has said yes to attending the session.", "number": "0", "approved": true, "story_group": "change_created", "location": "", "project_id": 3100, "charity_id": null, "story_category_id": 4173, "edited_by": 6134, "user_id": 6134, "updated_at": "2023-10-10T11:18:12.558+01:00", "created_at": "2023-10-10T11:18:11.000+01:00", "actual_created_at": "2023-10-10T11:18:11.706+01:00", "beneficiary_ids": [ 114707 ] } ] }

 

Example video

Screenshare - 2024-01-02 7_35_20 PM.mp4

 

What is a Story

Watch the explanation video: https://www.loom.com/share/8542bd5e2a5f4a05b676f2a27dc9a29f

  • A story record in the admin panel

Introduction

  • Stories are the main content format on Makerble

  • They are used to store text, media and progress towards goals (Changes and Indicators) whereby that progress can optionally be tagged to beneficiaries

  • Every story must belong to a single project

  • Every story must have a single author who is a user