This endpoint returns structured Story objects. As with all Kantata OX API endpoints, the returned data will be referenced in sorted order in the results array and will be indexed by ID in the stories top-level JSON key. Please see our Response Format section for more information.
Any of the below associations can be included in your request by providing the include param, e.g. include=association1,association2.
ancestors(Story) - Retrieves all of the tasks that the task is nested under (parents and top-level tasks). The response will includeancestor_ids, which references the data in thestoriestop-level key.assigned_role(Role) - Retrieves the authenticated user’s assigned role for the task. The response will includeassigned_role_id, which references the data in therolestop-level key.assignees(User) - Retrieves all users assigned to the task, excluding unnamed resources. The response will includeassignee_ids, which references the data in theuserstop-level key.attachments(Attachments::PostAttachment) - Retrieves all attachments in the task's posts. The response will includeattachment_ids, which references the data in theattachmentstop-level key. Must be used with theonlyparameter.creator(User) - Retrieves the user who created the task. The response will includecreator_id, which references the data in theuserstop-level key.current_assignments(Assignment) - Retrieves all assignments for the task. The response will includecurrent_assignment_ids, which references the data in theassignmentstop-level key.custom_field_values(CustomFieldValue) - Retrieves the task’s custom field values. The response will includecustom_field_value_ids, which references the data in thecustom_field_valuestop-level key.descendants(Story) - Retrieves all of the subtasks nested under this top-level task. The response will includedescendant_ids, which references the data in thestoriestop-level key.external_references(ExternalReference) - Includes references to external integrations for this object.followers(User) - Retrieves all users following the task. The response will includefollower_ids, which references the data in theuserstop-level key.google_documents(GoogleDocument) - Retrieves all Google documents for the task. The response will includegoogle_document_ids, which references the data in thegoogle_documentstop-level key. Must be used with theonlyparameter.parent(Story) - Retrieves the parent task that this subtask is nested directly under. The response will includeparent_id, which references the data in thestoriestop-level key.potential_workspace_resources(WorkspaceResource) - Retrieves the project's named resources who are not assigned to the task. The response will includepotential_workspace_resource_ids, which references the data in theworkspace_resourcestop-level key. Must be used with theonlyparameter.potential_workspace_resources_with_unnamed(WorkspaceResource) - Retrieves all of the project's resources (named and unnamed) who are not assigned to the task. The response will includepotential_workspace_resources_with_unnamed_ids, which references the data in theworkspace_resourcestop-level key. Must be used with theonlyparameter.replies(Post) - Retrieves all task posts, except for the first one. The response will includereply_ids, which references the data in thepoststop-level key. Must be used with theonlyparameter.root(Story) - Retrieves the top-level task that this subtask is nested under. The response will includeroot_id, which references the data in thestoriestop-level key.source_dependencies(StoryDependency) - Retrieves all tasks that this task is dependent on. The response will includesource_dependency_ids, which references the data in thestory_dependenciestop-level key.story_state_changes(StoryStateChange) - Retrieves all status changes the task has gone through. The response will includestory_state_change_ids, which references the data in thestory_state_changestop-level key. Must be used with theonlyparameter.story_tasks(StoryTask) - Retrieves all checklist items for the task. The response will includestory_task_ids, which references the data in thestory_taskstop-level key.sub_stories(Story) - Retrieves all direct subtasks of the task. This does not include the subtasks of its direct subtasks. The response will includesub_story_ids, which references the data in thestoriestop-level key.tags(ActsAsTaggableOn::Tag) - Retrieves all tags for the task. The response will includetag_ids, which references the data in thetagstop-level key.target_dependencies(StoryDependency) - Retrieves all tasks that are dependent on this task. The response will includetarget_dependency_ids, which references the data in thestory_dependenciestop-level key.workspace(Workspace) - Retrieves the project the task is in. The response will includeworkspace_id, which references the data in theworkspacestop-level key.workspace_resources(WorkspaceResource) - Retrieves the named resources who are assigned to the task. The response will includeworkspace_resource_ids, which references the data in theworkspace_resourcestop-level key.workspace_resources_with_unnamed(WorkspaceResource) - Retrieves all of the resources (named and unnamed) assigned to the task. The response will includeworkspace_resources_with_unnamed_ids, which references the data in theworkspace_resourcestop-level key.
Allows you to request one or more optional fields as an array.
Items Enum:"custom_task_status_id""read_only""can_edit""can_post""archived_editable""is_time_trackable_type""has_out_of_bounds_sads""can_align_time""formatted_description""parsed_description""render_description_markdown"
- https://api.mavenlink.com/api/v1https://api.mavenlink.com/api/v1/stories/{id}
curl -i -X GET \
'https://api.mavenlink.com/api/v1/stories/{id}?include=string&optional_fields=custom_task_status_id&show_deleted=false'The Story has been retrieved.
Response
{ "count": 0, "meta": { "count": 0, "page_count": 0, "page_number": 0, "page_size": 0 }, "results": [ { "key": "string", "id": "string" } ], "stories": { "property1": { "ancestor_ids": [ "string" ], "ancestry_depth": 0, "archived": true, "archived_editable": true, "assigned_role_id": "string", "assignee_ids": [ "string" ], "assignment_timestamped_at": "2019-08-24T14:15:22Z", "attachment_ids": [ "string" ], "billable": true, "budget_estimate_in_cents": 0, "budget_used_in_cents": 0, "can_align_time": true, "can_edit": true, "can_post": true, "created_at": "2019-08-24T14:15:22Z", "creator_id": "string", "current_assignment_ids": [ "string" ], "custom_field_value_ids": [ "string" ], "custom_task_status_id": 0, "deleted_at": "2019-08-24T14:15:22Z", "descendant_ids": [ "string" ], "description": "string", "due_date": "2019-08-24", "external_reference_ids": [ "string" ], "fixed_fee": true, "follower_ids": [ "string" ], "formatted_description": "string", "google_document_ids": [ "string" ], "has_out_of_bounds_sads": true, "invoiced_balance_in_cents": 0, "is_time_trackable_type": true, "logged_billable_time_in_minutes": 0, "logged_nonbillable_time_in_minutes": 0, "parent_id": "string", "parsed_description": "string", "percentage_complete": 0, "position": 0, "potential_workspace_resource_ids": [ "string" ], "potential_workspace_resources_with_unnamed_ids": [ "string" ], "priority": 0, "project_plan": true, "read_only": true, "render_description_markdown": true, "reply_ids": [ "string" ], "root_id": "string", "source_dependency_ids": [ "string" ], "start_date": "2019-08-24", "state": "string", "status": "string", "story_state_change_ids": [ "string" ], "story_task_ids": [ "string" ], "story_type": "string", "sub_stories_billable_time_in_minutes": 0, "sub_stories_budget_estimate_in_cents": 0, "sub_stories_budget_used_in_cents": 0, "sub_stories_time_estimate_in_minutes": 0, "sub_story_count": 0, "sub_story_ids": [ "string" ], "subtree_depth": 0, "tag_ids": [ "string" ], "target_dependency_ids": [ "string" ], "time_estimate_in_minutes": 0, "time_trackable": true, "title": "string", "uninvoiced_balance_in_cents": 0, "updated_at": "2019-08-24T14:15:22Z", "weight": 0, "workspace_id": "string", "workspace_resource_ids": [ "string" ], "workspace_resources_with_unnamed_ids": [ "string" ] }, "property2": { "ancestor_ids": [ "string" ], "ancestry_depth": 0, "archived": true, "archived_editable": true, "assigned_role_id": "string", "assignee_ids": [ "string" ], "assignment_timestamped_at": "2019-08-24T14:15:22Z", "attachment_ids": [ "string" ], "billable": true, "budget_estimate_in_cents": 0, "budget_used_in_cents": 0, "can_align_time": true, "can_edit": true, "can_post": true, "created_at": "2019-08-24T14:15:22Z", "creator_id": "string", "current_assignment_ids": [ "string" ], "custom_field_value_ids": [ "string" ], "custom_task_status_id": 0, "deleted_at": "2019-08-24T14:15:22Z", "descendant_ids": [ "string" ], "description": "string", "due_date": "2019-08-24", "external_reference_ids": [ "string" ], "fixed_fee": true, "follower_ids": [ "string" ], "formatted_description": "string", "google_document_ids": [ "string" ], "has_out_of_bounds_sads": true, "invoiced_balance_in_cents": 0, "is_time_trackable_type": true, "logged_billable_time_in_minutes": 0, "logged_nonbillable_time_in_minutes": 0, "parent_id": "string", "parsed_description": "string", "percentage_complete": 0, "position": 0, "potential_workspace_resource_ids": [ "string" ], "potential_workspace_resources_with_unnamed_ids": [ "string" ], "priority": 0, "project_plan": true, "read_only": true, "render_description_markdown": true, "reply_ids": [ "string" ], "root_id": "string", "source_dependency_ids": [ "string" ], "start_date": "2019-08-24", "state": "string", "status": "string", "story_state_change_ids": [ "string" ], "story_task_ids": [ "string" ], "story_type": "string", "sub_stories_billable_time_in_minutes": 0, "sub_stories_budget_estimate_in_cents": 0, "sub_stories_budget_used_in_cents": 0, "sub_stories_time_estimate_in_minutes": 0, "sub_story_count": 0, "sub_story_ids": [ "string" ], "subtree_depth": 0, "tag_ids": [ "string" ], "target_dependency_ids": [ "string" ], "time_estimate_in_minutes": 0, "time_trackable": true, "title": "string", "uninvoiced_balance_in_cents": 0, "updated_at": "2019-08-24T14:15:22Z", "weight": 0, "workspace_id": "string", "workspace_resource_ids": [ "string" ], "workspace_resources_with_unnamed_ids": [ "string" ] } }, "external_references": { "property1": { "created_at": "2019-08-24T14:15:22Z", "external_link": "string", "external_message": "string", "external_status": "string", "last_synced_at": "2019-08-24T14:15:22Z", "locked": true, "service_model": "string", "service_model_ref": "string", "service_name": "string", "status": "string", "subject_id": 0, "subject_ref": { "key": "string", "id": "string" }, "subject_type": "string", "updated_at": "2019-08-24T14:15:22Z" }, "property2": { "created_at": "2019-08-24T14:15:22Z", "external_link": "string", "external_message": "string", "external_status": "string", "last_synced_at": "2019-08-24T14:15:22Z", "locked": true, "service_model": "string", "service_model_ref": "string", "service_name": "string", "status": "string", "subject_id": 0, "subject_ref": { "key": "string", "id": "string" }, "subject_type": "string", "updated_at": "2019-08-24T14:15:22Z" } }, "workspace_resources": { "property1": { "created_at": "2019-08-24T14:15:22Z", "custom_field_value_ids": [ "string" ], "display_label": "string", "external_reference_ids": [ "string" ], "full_name": "string", "label": "string", "organization_membership_id": "string", "participation_id": "string", "photo_path": "string", "resource_bill_rate": 0, "resource_cost_rate": 0, "role_id": "string", "role_initials": "string", "role_name": "string", "updated_at": "2019-08-24T14:15:22Z", "user_id": "string", "workspace_id": 0, "workspace_title": "string" }, "property2": { "created_at": "2019-08-24T14:15:22Z", "custom_field_value_ids": [ "string" ], "display_label": "string", "external_reference_ids": [ "string" ], "full_name": "string", "label": "string", "organization_membership_id": "string", "participation_id": "string", "photo_path": "string", "resource_bill_rate": 0, "resource_cost_rate": 0, "role_id": "string", "role_initials": "string", "role_name": "string", "updated_at": "2019-08-24T14:15:22Z", "user_id": "string", "workspace_id": 0, "workspace_title": "string" } }, "workspaces": { "property1": { "access_level": "string", "account_color_id": "string", "account_id": 0, "account_insights_mapping_ids": [ "string" ], "actual_fees_includes_additional_line_items": true, "actual_fees_includes_expenses": true, "approver_id": "string", "approver_ids": [ "string" ], "archived": true, "billable_minutes": 0, "billing_milestone_ids": [ "string" ], "budget_remaining": "string", "budget_used": "string", "budget_used_in_cents": 0, "budgeted": true, "can_create_line_items": true, "can_invite": true, "change_orders_enabled": true, "client_lead_name": "string", "client_role_name": "string", "consultant_role_name": "string", "created_at": "2019-08-24T14:15:22Z", "creator_id": "string", "currency": "string", "currency_base_unit": 0, "currency_symbol": "string", "current_status_report_id": "string", "current_user_participation_id": "string", "custom_field_value_ids": [ "string" ], "default_rate": "string", "description": "string", "due_date": "2019-08-24", "effective_due_date": "2019-08-24", "estimated_minutes": 0, "exclude_archived_stories_percent_complete": true, "expenses_in_burn_rate": true, "external_link": { "url": "string", "text": "string" }, "external_reference_ids": [ "string" ], "financial_viewer_ids": [ "string" ], "has_active_expense_report_submissions": true, "has_active_timesheet_submissions": true, "has_budget_access": true, "incoming_email_address": "string", "lock_date": "2019-08-24", "minutes_logged": 0, "next_uncompleted_milestone_id": "string", "non_billable_minutes": 0, "over_budget": true, "participant_ids": [ "string" ], "participation_ids": [ "string" ], "percent_of_budget_used": 0, "percentage_complete": 0, "permissions": { "can_upload_files": true, "can_private_message": true, "can_join": true, "is_participant": true, "access_level": "string", "team_lead": true, "user_is_client": true, "can_change_price": true, "can_change_story_billable": true, "can_post": true, "can_edit": true, "restricted": true, "can_see_financials": true, "is_guest_on_project": true }, "possible_approver_ids": [ "string" ], "posts_require_privacy_decision": true, "price": "string", "price_in_cents": 0, "primary_counterpart_id": "string", "primary_maven_id": "string", "primary_workspace_group_id": "string", "provider_lead_name": "string", "rate_card_id": 0, "require_expense_approvals": true, "require_notes_on_time_entries": true, "require_time_approvals": true, "revenue_recognition_method_id": "string", "revenue_recognition_method_name": "string", "stage": "string", "start_date": "2019-08-24", "status": { "color": "string", "key": "string", "message": "string" }, "status_report_ids": [ "string" ], "stories_are_fixed_fee_by_default": true, "target_margin": 0.1, "task_status_set_id": "string", "task_status_set_name": "string", "task_statuses": [ "string" ], "tasks_default_non_billable": true, "time_trackable": true, "timesheet_submission_ids": [ "string" ], "title": "string", "total_expenses_in_cents": 0, "total_invoiced": "string", "total_minutes_approved": 0, "updated_at": "2019-08-24T14:15:22Z", "workspace_group_ids": [ "string" ], "workspace_invoice_preference_id": 0, "workspace_resource_ids": [ "string" ], "workspace_resources_with_unnamed_ids": [ "string" ] }, "property2": { "access_level": "string", "account_color_id": "string", "account_id": 0, "account_insights_mapping_ids": [ "string" ], "actual_fees_includes_additional_line_items": true, "actual_fees_includes_expenses": true, "approver_id": "string", "approver_ids": [ "string" ], "archived": true, "billable_minutes": 0, "billing_milestone_ids": [ "string" ], "budget_remaining": "string", "budget_used": "string", "budget_used_in_cents": 0, "budgeted": true, "can_create_line_items": true, "can_invite": true, "change_orders_enabled": true, "client_lead_name": "string", "client_role_name": "string", "consultant_role_name": "string", "created_at": "2019-08-24T14:15:22Z", "creator_id": "string", "currency": "string", "currency_base_unit": 0, "currency_symbol": "string", "current_status_report_id": "string", "current_user_participation_id": "string", "custom_field_value_ids": [ "string" ], "default_rate": "string", "description": "string", "due_date": "2019-08-24", "effective_due_date": "2019-08-24", "estimated_minutes": 0, "exclude_archived_stories_percent_complete": true, "expenses_in_burn_rate": true, "external_link": { "url": "string", "text": "string" }, "external_reference_ids": [ "string" ], "financial_viewer_ids": [ "string" ], "has_active_expense_report_submissions": true, "has_active_timesheet_submissions": true, "has_budget_access": true, "incoming_email_address": "string", "lock_date": "2019-08-24", "minutes_logged": 0, "next_uncompleted_milestone_id": "string", "non_billable_minutes": 0, "over_budget": true, "participant_ids": [ "string" ], "participation_ids": [ "string" ], "percent_of_budget_used": 0, "percentage_complete": 0, "permissions": { "can_upload_files": true, "can_private_message": true, "can_join": true, "is_participant": true, "access_level": "string", "team_lead": true, "user_is_client": true, "can_change_price": true, "can_change_story_billable": true, "can_post": true, "can_edit": true, "restricted": true, "can_see_financials": true, "is_guest_on_project": true }, "possible_approver_ids": [ "string" ], "posts_require_privacy_decision": true, "price": "string", "price_in_cents": 0, "primary_counterpart_id": "string", "primary_maven_id": "string", "primary_workspace_group_id": "string", "provider_lead_name": "string", "rate_card_id": 0, "require_expense_approvals": true, "require_notes_on_time_entries": true, "require_time_approvals": true, "revenue_recognition_method_id": "string", "revenue_recognition_method_name": "string", "stage": "string", "start_date": "2019-08-24", "status": { "color": "string", "key": "string", "message": "string" }, "status_report_ids": [ "string" ], "stories_are_fixed_fee_by_default": true, "target_margin": 0.1, "task_status_set_id": "string", "task_status_set_name": "string", "task_statuses": [ "string" ], "tasks_default_non_billable": true, "time_trackable": true, "timesheet_submission_ids": [ "string" ], "title": "string", "total_expenses_in_cents": 0, "total_invoiced": "string", "total_minutes_approved": 0, "updated_at": "2019-08-24T14:15:22Z", "workspace_group_ids": [ "string" ], "workspace_invoice_preference_id": 0, "workspace_resource_ids": [ "string" ], "workspace_resources_with_unnamed_ids": [ "string" ] } }, "users": { "property1": { "abbreviated_timezone": "string", "account_membership_id": "string", "bio": "string", "city": "string", "classification": "string", "country": "string", "custom_field_value_ids": [ "string" ], "email_address": "string", "external_reference_ids": [ "string" ], "full_name": "string", "headline": "string", "last_site_activity": "2019-08-24T14:15:22Z", "manager_id": "string", "photo_path": "string", "role_id": "string", "skill_ids": [ "string" ], "skill_membership_ids": [ "string" ], "state": "string", "website": "string", "work_sample_ids": [ "string" ] }, "property2": { "abbreviated_timezone": "string", "account_membership_id": "string", "bio": "string", "city": "string", "classification": "string", "country": "string", "custom_field_value_ids": [ "string" ], "email_address": "string", "external_reference_ids": [ "string" ], "full_name": "string", "headline": "string", "last_site_activity": "2019-08-24T14:15:22Z", "manager_id": "string", "photo_path": "string", "role_id": "string", "skill_ids": [ "string" ], "skill_membership_ids": [ "string" ], "state": "string", "website": "string", "work_sample_ids": [ "string" ] } }, "assignments": { "property1": { "allocated_minutes": 0, "assignee_id": "string", "created_at": "2019-08-24T14:15:22Z", "current": true, "estimated_minutes": 0, "external_reference_ids": [ "string" ], "resource_id": 0, "story_allocation_day_ids": [ "string" ], "story_id": "string", "updated_at": "2019-08-24T14:15:22Z" }, "property2": { "allocated_minutes": 0, "assignee_id": "string", "created_at": "2019-08-24T14:15:22Z", "current": true, "estimated_minutes": 0, "external_reference_ids": [ "string" ], "resource_id": 0, "story_allocation_day_ids": [ "string" ], "story_id": "string", "updated_at": "2019-08-24T14:15:22Z" } }, "story_tasks": { "property1": { "completed": true, "completed_at": "2019-08-24T14:15:22Z", "completed_by_id": "string", "created_at": "2019-08-24T14:15:22Z", "name": "string", "position": 0, "story_id": "string", "updated_at": "2019-08-24T14:15:22Z" }, "property2": { "completed": true, "completed_at": "2019-08-24T14:15:22Z", "completed_by_id": "string", "created_at": "2019-08-24T14:15:22Z", "name": "string", "position": 0, "story_id": "string", "updated_at": "2019-08-24T14:15:22Z" } }, "tags": { "property1": { "name": "string", "status": "string" }, "property2": { "name": "string", "status": "string" } }, "story_state_changes": { "property1": { "created_at": "2019-08-24T14:15:22Z", "formatted_state": "string", "state": "string", "story_id": "string", "updated_at": "2019-08-24T14:15:22Z", "user_id": "string" }, "property2": { "created_at": "2019-08-24T14:15:22Z", "formatted_state": "string", "state": "string", "story_id": "string", "updated_at": "2019-08-24T14:15:22Z", "user_id": "string" } }, "posts": { "property1": { "attachment_ids": [ "string" ], "created_at": "2019-08-24T14:15:22Z", "external_reference_ids": [ "string" ], "formatted_message": "string", "google_document_ids": [ "string" ], "has_attachments": true, "message": "string", "newest_reply_at": "2019-08-24T14:15:22Z", "newest_reply_id": "string", "newest_reply_user_id": "string", "parsed_message": "string", "private": true, "recipient_ids": [ "string" ], "reply": true, "reply_count": 0, "reply_ids": [ "string" ], "story_id": "string", "subject_id": 0, "subject_ref": { "key": "string", "id": "string" }, "subject_title": "string", "subject_type": "string", "updated_at": "2019-08-24T14:15:22Z", "user_id": "string", "workspace_id": "string" }, "property2": { "attachment_ids": [ "string" ], "created_at": "2019-08-24T14:15:22Z", "external_reference_ids": [ "string" ], "formatted_message": "string", "google_document_ids": [ "string" ], "has_attachments": true, "message": "string", "newest_reply_at": "2019-08-24T14:15:22Z", "newest_reply_id": "string", "newest_reply_user_id": "string", "parsed_message": "string", "private": true, "recipient_ids": [ "string" ], "reply": true, "reply_count": 0, "reply_ids": [ "string" ], "story_id": "string", "subject_id": 0, "subject_ref": { "key": "string", "id": "string" }, "subject_title": "string", "subject_type": "string", "updated_at": "2019-08-24T14:15:22Z", "user_id": "string", "workspace_id": "string" } }, "attachments": { "property1": { "created_at": "2019-08-24T14:15:22Z", "creator_name": "string", "deletable": true, "deleted_at": "2019-08-24T14:15:22Z", "filename": "string", "filesize": 0, "previewable": true, "updated_at": "2019-08-24T14:15:22Z", "url": "string", "view_in_new_tab": true }, "property2": { "created_at": "2019-08-24T14:15:22Z", "creator_name": "string", "deletable": true, "deleted_at": "2019-08-24T14:15:22Z", "filename": "string", "filesize": 0, "previewable": true, "updated_at": "2019-08-24T14:15:22Z", "url": "string", "view_in_new_tab": true } }, "story_dependencies": { "property1": { "created_at": "2019-08-24T14:15:22Z", "dependency_type": 0, "lag": 0, "source_id": "string", "target_id": "string", "updated_at": "2019-08-24T14:15:22Z" }, "property2": { "created_at": "2019-08-24T14:15:22Z", "dependency_type": 0, "lag": 0, "source_id": "string", "target_id": "string", "updated_at": "2019-08-24T14:15:22Z" } }, "custom_field_values": { "property1": { "account_id": 0, "can_edit": true, "created_at": "2019-08-24T14:15:22Z", "custom_field_id": "string", "custom_field_name": "string", "display_value": "string", "external_reference_ids": [ "string" ], "selected_choice_ids": [ "string" ], "setter_id": "string", "subject_id": 0, "subject_ref": { "key": "string", "id": "string" }, "subject_type": "string", "type": "string", "updated_at": "2019-08-24T14:15:22Z", "value": "string" }, "property2": { "account_id": 0, "can_edit": true, "created_at": "2019-08-24T14:15:22Z", "custom_field_id": "string", "custom_field_name": "string", "display_value": "string", "external_reference_ids": [ "string" ], "selected_choice_ids": [ "string" ], "setter_id": "string", "subject_id": 0, "subject_ref": { "key": "string", "id": "string" }, "subject_type": "string", "type": "string", "updated_at": "2019-08-24T14:15:22Z", "value": "string" } }, "roles": { "property1": { "created_at": "2019-08-24T14:15:22Z", "deleted_at": "2019-08-24T14:15:22Z", "external_reference_ids": [ "string" ], "name": "string", "updated_at": "2019-08-24T14:15:22Z" }, "property2": { "created_at": "2019-08-24T14:15:22Z", "deleted_at": "2019-08-24T14:15:22Z", "external_reference_ids": [ "string" ], "name": "string", "updated_at": "2019-08-24T14:15:22Z" } } }