Freedcamp MCP Server

/projects GET /projects - returns the same data as /sessions/current:GET request returns except user_id. You may pass "f_recent_projects_ids=1" GET parameter, then the response will contain 'recent_project_ids' array with recently visited projects ids (the same as on projects dashboard). Order is from most recently visited to less recently. Only projects visited using web UI are marked as recent. Avoid using f_recent_projects_ids too often (for example more than once an hour). /projects/project_id - returns the same data as /sessions/current:GET request returns except: 1) user_id is not returned; 2) "projects" array contains only specified project (or it's empty if a project is not found) 3) project inside "projects" array has additional field "notifications", containing all unread notifications. See /notifications for "notifications" structure description. 4) project inside "projects" array has an additional field "f_subtasks_adv", containing boolean true or false. It reflects if a user is able to create advanced subtasks in the project. 5) project inside "projects" array has an additional field "f_can_add_tasks", containing boolean true or false. It reflects if a user is able to create tasks in the project. POST Input data: name description project_name can be empty if f_first = 1 (default will be used). Max allowed length is 255 symbols, the recommended length is ~50 symbols. project_description can be empty project_color can be empty or contain HEX number (w/o "#") todo_view_type kanban|default, so far use "default" value group_id project group. If empty, group_name should be set group_name if it is not empty, will be created a new group with this name (passed group_id will be ignored). When f_first is true, both group_id and group_name can be empty - the default group will be created. Otherwise, an error will be triggered. changed_users list of invitations to users. It can be empty or absent. See projects/project_id:PUT for structure description (only "added" users will be processed) Example: { "project_name":"Name", "project_description":"Some descr", "project_color":"34ad22", "todo_view_type":"kanban", "f_first":true, "group_id":"", "group_name":"new group", "changed_users":{ "added":[ { "row_id":"any_id_to_link_validation_to_email", "email":"some_email", "first_name":"fir!!st_name", "last_name":"last!!_name" }, { "row_id":"any_id_to_link_validation_to_email", "email":"some_email", "first_name":"first_name2", "last_name":"last_name2" } ] } } Output (inside 'data'): the same as for /projects/project_id:GET PUT (actual request should be /projects/project_id:POST) Input data: name description project_name mandatory project_description can be empty project_color mandatory group_id mandatory if group_name is empty group_name mandatory if group_id is empty. If present, group_id is ignored f_active optional. Possible values: true|false. If it is present, will change project state according to the value. f_only_users_update optional. Possible values: true|false. If it is present, will change project users only. changed_users list of added, deleted and updated users. It can be empty or absent. See projects/project_id:POST for structure description. Changed users structure example is below: { "added": [{ "row_id": "any_id_to_link_validation_to_email", "email": "some_email", "first_name": "fir!!st_name", "last_name": "last!!_name" }], "updated": [{ "user_id": "309953", "team_id": "7000" }], "deleted": [{ "user_id": "377131" }, { "user_id": "377132" }] } Fields for an element inside added: name description row_id invitation id (generated by client app) - if this invitation is in error, id will be used to link error to the invitation in the response email mandatory first_name can be empty last_name can be empty Fields for an element inside updated: name description user_id mandatory team_id the same as role_id (later role_id where it present will be team_id). This is the only field available for editing. Fields for an element inside deleted: name description user_id mandatory Example of /projects/project_id:POST request: { "project_name": "Name", "project_description": "Some descr", "project_color": "34ad22", "todo_view_type": "kanban", "f_first": true, "group_id": "267282", "group_name": "new group", "changed_users": { "updated": [{ "user_id": "309953", "team_id": "7000" }], "deleted": [{ "user_id": "377131" }, { "user_id": "377132" }] } } Output (inside 'data'): the same as for /projects/project_id:GET DELETE WARNING: Is not supported now /projects/project_id:DELETE /tasks GET /tasks - returns a list of all tasks user has access to /tasks/?project_id=xxx - list of tasks in the project /tasks/task_id - list of tasks which contains only the task with given task_id Custom fields To include custom fields data in the response you need to add "f_cf=1" parameter, example: /tasks/?project_id=xxx&f_cf=1. Only fetch is supported for custom fields (no insert/update/delete). When you pass f_cf=1, the response will contain an additional array of custom fields templates used in the resulting task list. Tags You may pass "f_include_tags=1" GET parameter, then the response will contain 'tags' array with tag ids assigned to the item. Limits All /tasks:GET requests support limit and offset parameters. Example: "/tasks?limit=2&offset=2". Current default (and maximum allowed) limit for public API is 200. All responses contain "meta" field: "meta": { "has_more": true, // always presents "total_count": 1362 // presents if has_more = true } name description has_more is true if there are more results after the last returned result in the response, and false otherwise. total_count presents if show_more = true and contains all available results count. WARN: currently limit, offset, total_count values are applied to the top-level tasks. All subtasks are ignored when a limit is applied, and total_count is calculated. Example To fetch all the tasks, you need to execute set of requests like https://freedcamp.com/api/v1/tasks?limit=200&offset=0 https://freedcamp.com/api/v1/tasks?limit=200&offset=200 https://freedcamp.com/api/v1/tasks?limit=200&offset=400 .... while there are results or meta.has_more is true. Each request may return more than 200 tasks, if there are subtasks. All subtasks of the task are always returned in the one request (are not split between pages). Filtration and order /tasks and /tasks/?project_id=xxx requests support filtration and ordering. Filters/order can be applied in any combination. Supported filters: name description status check constants wiki for possible values. For example, to get only not started and started tasks, you should use: "/tasks?status[]=0&status[]=2" assigned_to_id accepts integer values containing user id or one of Assignments constants from constants wiki created_by_id accepts integer values containing user id due_date[from] accepts a date in format YYYY-MM-DD. If set, only tasks with the due date set and due date >= due_date[from] will be returned due_date[to] accepts a date in format YYYY-MM-DD. If set, only tasks with the due date set and due date <= due_date[to] will be returned created_date[from] accepts a date in format YYYY-MM-DD. If set, only tasks with the creation date >= created_date[from] will be returned created_date[to] accepts a date in format YYYY-MM-DD. If set, only tasks with the creation date <= created_date[to] will be returned f_with_archived accepts 1/0 values. If 1 is passed, tasks from archived projects will be included to the response. If omitted or 0 is passed, only tasks from active projects are fetched. lists_status Determines the status (i.e. active or archived) of Task Lists to fetch tasks from. Accepts "active", "archived", "all" values. Omitting is equal to "active". (Note: "Task list" is the new name for "Task Group". The old name is still used in API and this wiki). Supported orders: priority: tasks with no priority set are supposed to have the lowest priority. due_date: tasks with no due date set are always placed at the list end despite the order direction. WARN: if there are many orders in the request, only the first one will be applied. WARN: ordering is applied to Tasks groups for all orders except due_date. So if you have two tasks groups in output, there will be all tasks from the first group, and then all tasks from the second group in the output. For due_date order, Tasks groups order is ignored. WARN: when ordering, subtasks are always following their parent tasks if these tasks are present in the output. If not valid filter or order value is passed, this value is ignored. Example: /tasks?status[]=0&due_date[from]=2017-02-01&due_date[to]=2017-02-28&created_date[from]=2017-01-01&&assigned_to_id[]=13&assigned_to_id[]=-1&assigned_to_id[]=0&created_by_id[]=15&order[due_date]=asc&lists_status=active Output example for /tasks:GET: Output: tasks: list of tasks with the next fields: name description id task id assigned_to_id user id task is assigned to. May have values -1 (ASSIGNED_EVERYONE) and 0 (ASSIGNED_NOONE). created_by_id user id who created the task task_group_id project_id priority possible values: 0 (none), 1 (low), 2 (medium), 3 (high). title description raw description, with Freedcamp tags like [fcattach]. WARN - you should show this data to the user when editing. description_processed (absent if it's not a get one task by id) processed description, where [fcattach] tags are replaced with actual images with link. WARN - is present only when you request only one task, absent otherwise. You should show to user this data when showing task (and use raw "description" when editing). status one of the next values: 0 (not started), 1 (completed), 2 (in progress) comments_count files_count files attached to the task (files attached to task comments are not counted) completed_ts if was completed, ts when it happened, null otherwise start_ts null if it was not set due_ts null if it was not set created_ts task_group_name f_archived_list false if the task is in an active task list, true if the task is in an archived task list priority_title a title of the corresponding value in 'priority' field status_title title of the corresponding value in 'status' field assigned_to_fullname name of a user task is assigned to (will be discussed if we need it and in what format) can_delete (absent if a query is for more than one project) can_edit (absent if a query is for more than one project) can_assign (absent if a query is for more than one project) can_progress (absent if a query is for more than one project) can_comment (absent if a query is for more than one project) comments (absent if it's not a get task by id) list of comments. Comments structure is described below files (absent if it's not a get task by id) list of files attached to the task. See /files:GET for structure description url URL for the task cf_tpl_id custom fields template id (if linked with the task) custom_fields (absent if custom fields are not requested) an array of custom fields values used for the task h_level shows the task nesting level, 0 for top-level tasks. h_parent_id shows the parent task id. Is an empty string for top-level tasks. h_top_id shows the top parent task id (so is equal to h_parent_id for subtasks with h_level=1, and differs for subtasks with h_level > 1). Is an empty string for top-level tasks. r_rule empty if the task is not recurring order set by user order inside tasks group (using d&d). By default tasks in output are ordered by this field inside their tasks groups. WARN! It's possible that several tasks inside the same group have the same order value including default value (0). WARN! It's possible that subtask has order equal to or greater than its parent(s). In this case, API ignores the order of subtask and places subtask after parent task (if a parent is present in output). WARN! This field is NOT equal to the task position in the returned list. f_adv_subtask (absent if it's not a get one task by id) shows if this is an advanced subtask or not. True for advanced subtasks, false for usual tasks and not advanced subtasks. Advanced subtasks have the same properties (all editable) that usual tasks. Not advanced subtasks have title and status only, and status can be set only in "TODO_NOT_STARTED" or "TODO_COMPLETED" (no "TODO_IN_PROGRESS" status). Not advanced subtasks can't have comments as well. It's possible for a user to have access to both advanced and not advanced subtasks at the same time even inside the same project. Example: "tasks": [ { "id": "1528", "h_parent_id": "1525", "h_top_id": "1524", "h_level": "2", "f_adv_subtask": false, // only presents for getting a task by id "assigned_to_id": null, "created_by_id": "167", "task_group_id": "272", "project_id": "305", "priority": 0, "title": "tngfng", "description": "<p>пат<br />\n </p>\n", "status": 0, "order": 3, "comments_count": 0, "files_count": 0, "completed_ts": null, "start_ts": null, "due_ts": 1440745200, "created_ts": 1440686274, "task_group_name": "new", "f_archived_list": false, "priority_title": "none", "status_title": "no progress", "assigned_to_fullname": "Unassigned", "r_rule": "RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;UNTIL=20200430T000000", "can_delete": true, "can_edit": true, "can_assign": true, "can_progress": true, "can_comment": true, "comments": [{...}, {...}, ...], "files": [{...}, {...}, ...], "url": "https://freedcamp.com/somename_LxR/project_Devel_yOf/todos/7666346/", "cf_tpl_id": "15", "custom_fields": [ { "cf_id": "18", "value": "211" }, { "cf_id": "19", "value": "1" } ] }, .... ] Comments structure: the same as /comments:POST returns. If custom fields data is requested and there were custom fields templates linked to some tasks in the list, list of these templates will be returned in a separate array "cf_templates". Here is an example of its structure: "cf_templates": [ { "id": "17", "title": "all fields", "fields": [ { "id": "20", "title": "drop very long name", "type": "dropdown", "f_required": false, "order": 0, "dd_options": [ "the first option", "the second option", ] }, { "id": "1", "title": "text", "type": "text_field", "f_required": false, "order": 1, "dd_options": null }, { "id": "2", "title": "area", "type": "textarea", "f_required": false, "order": 2, "dd_options": null }, { "id": "19", "title": "check", "type": "checkbox", "f_required": false, "order": 3, "dd_options": null }, { "id": "18", "title": "numn", "type": "number", "f_required": false, "order": 4, "dd_options": null }, { "id": "17", "title": "date", "type": "date", "f_required": false, "order": 5, "dd_options": null } ] } ] dd_options array contains values for the dropdown type of custom field. For other field types, this field is set to null. Inside "custom_fields" array with values for the task, value for the field with dropdown type is the number of the value in the dd_options array (starting from 0). Also for dropdowns, there is an additional field dd_actual_value which contains the actual value (so you may know it without extracting it from dd_options by id). POST Input data: name description title description can be an empty string project_id task_group_id can be empty or absent (task will be added to the first task list). priority priority id. See priorities for :get. assigned_to_id should contain assigned to user id OR one of the two constants: -1 (ASSIGNED_EVERYONE) and 0 (ASSIGNED_NOONE) start_date can be empty or absent, the format is YYYY-MM-DD (empty value will be used if start_date is not allowed for the plan. Old start_date will be overridden in this case, if any). r_rule the recurrence rule in iCalendar (RFC 5545) format, can be an empty string or absent due_date can be empty or absent, the format is YYYY-MM-DD attached_ids an array of files uploaded previously with temporary=1 flag h_parent_id can be absent or empty. It contains a parent task id. Note: parent task should be in the same tasks group as passed task_group_id. WARN! if a project, where subtask is added to, does not allow advanced subtasks (i.e. has f_subtasks_adv = false, see above), added subtask should contain empty string for description and due_date fields, and "0" for priority and assigned_to_id fields. Also, the parent task should not be a subtask. In case when other values are passed, they will be implicitly fixed to the right values with triggering an error sent to Freedcamp developers. h_ stands for Hierarchy. Request example: {"title": "22222", "description": "wwwwwww", "project_id": "305", "task_group_id": "272", "priority": "1", "assigned_to_id": "1", "due_date": "2015-08-28", "r_rule": "RRULE:FREQ=DAILY;COUNT=5", "attached_ids": [1296, 1297]} Output: the same as /tasks/task_id:GET PUT (actual request should be /tasks/task_id:POST) WARN! If an edited task is a subtask (h_parent_id is not empty) and has f_adv_subtask = false, edited data should contain empty string for description and due_date fields, and "0" for priority and assigned_to_id fields, or these fields should be absent. Also, the parent task should not be a subtask. No limits if f_adv_subtask = true. Input data: The same set as for /tasks:POST. You may pass only changed parameters as well and skip passing not changed. h_parent_id - can be absent or empty. If it is absent, the current parent id value is not changed during the query. If it is not empty and the edited task is not a subtask, it becomes a subtask. If is empty and edited task is a subtask, it becomes a task. All children tasks of the edited task are still its children in any case. Note: parent task should be in the same tasks group as passed task_group_id. Request data example: {"title": "QQrgfbQQfdvQ!!!!", "description": "dvsdvdsfvdfv", "task_group_id": "276", "priority": "2", "assigned_to_id": "123", "due_date": "2015-08-13", "status": "2", "attached_ids": [1296, 1297]} Output: the same as /tasks/task_id:GET /tasks:POST(PUT) with custom fields manipulation With usual data passed when adding a task, you may pass additional fields: "cf_tpl_id": 1, "custom_fields": [{"cf_id": "1", "value": "1"}, {"cf_id": "2", "value": "some text"}] Custom fields data structure is described in /tasks:GET section above. Warn - do not pass 'cf_tpl_id' and 'custom_fields' if you do not intend to actually change anything in custom fields. Only passed custom fields values will be updated. Request data example to unlink custom field template from a task: /tasks/task_id:PUT {"cf_tpl_id": null} DELETE /tasks/task_id:DELETE /files GET /files/file_id - returns requested file inside files array Output: files: list of files with the following fields: name description id file id name name of the file (as on user's PC when uploaded) url download URL. Expires after some time, for example after 1 hour. It can be absent or empty. It always presents if requesting one file, or files array is a part of item data like task or comment. thumb_url if f_image is true, it contains thumbnail URL, otherwise it is null. size in bytes version_id first_version_id you may need it to upload a newer version of the file is_last_version project_id files_group_id if a file is inside some files group, it's id, "0" otherwise file_type file mime type app_id application to which file belongs to item_id item to which file attached to. Can be "0". comment_id comment to which file attached to. Can be "0". user_id a user who uploaded the file f_temporary the file was uploaded for an item to be created (task, comment). You should pass file_id when submitting this item later to link it location where the file is placed physically. Possible values are: storage, gdrive, onedrive, dropbox created_ts f_image if a file is image or not. Images may have thumb_url filed filled Example: "files": [ { "id": "1293", "name": "win.png", "url": "https://freedcampfilestorage_test.s3.amazonaws.com/dsfv_JiP/win-89617.png?AWSAccessKeyId=AKIAJMBJBCR6Y7ZBMEEA&Expires=1441557155&Signature=smKZNFrjlfWdtffr0ie2WIqbJDo%3D", "thumb_url": "https://freedcampfilestorage_test.s3.amazonaws.com/dsfv_JiP/win-89617_thumb.png?AWSAccessKeyId=AKIAJMBJBCR6Y7ZBMEEA&Expires=1441557155&Signature=0o3V5qojh2lCQofcvTN4K7%2FqGrk%3D", "size": 74197, "version_id": 1, "first_version_id": 1293, "is_last_version": true, "project_id": "316", "files_group_id": "0", "comments_count": 0, "file_type": "image/png", "app_id": "2", "item_id": "1549", "comment_id": "0", "user_id": "167", "f_temporary": false, "created_ts": 1441466810, "f_image": true }, .... ] POST name description application_id should be always set project_id item_id can be empty or absent if added directly to Files application or a file is temporary, otherwise should present (even for comments) comment_id can be empty or absent if it's not attaching a file to comment or file is temporary temporary the file is uploaded for an item to be created (task, comment). You should pass returned file_id when submitting this item later to link it. file - additional form-encoded field (except JSON "data") Example: {"project_id": "309", "application_id": "2", "item_id": "1560", "comment_id": "514", "temporary":0} file: binary file data* * i. e. request body contains 2 fields, string "data" and file "avatar", encoded as a form-data Output: the same as /files/file_id:GET Note, that you should not attach files to items (tasks, comments etc) directly. So far it will cause wrong files_count counter for the item. It will be changed later. DELETE /files/file_id:DELETE /comments POST Input data: name description item_id Item id to add a comment for app_id Application id (wiki). Supported apps are APP_TODOS, APP_FILES, APP_DISCUSSIONS, APP_BUGTRACKER, APP_WIKI, APP_CALENDAR. description Text content, HTML is supported task_id the deprecated parameter which will be removed attached_ids an array of files uploaded previously with temporary=1 flag. Can be empty or absent Example: {"item_id": "1549","app_id": "2", "description": "wwwwwww", "attached_ids":[1307, 1297]} Output: name description id description raw description, with Freedcamp tags like. WARN - you should show this data to the user when editing. description_processed processed description, where [fcattach] tags are replaced with actual images with a link. You should show to a user this data when showing comment (and use raw "description" when editing). created_by_id author id created_ts likes_count f_liked if the comment is liked by the current user files list of files attached to the comment. See /files:GET for structure description can_edit boolean - if the current user is able to edit the comment f_unread boolean - if the comment is unread. A comment is marked as read after fetching by API user_full_name author name url comment URL Note: for /comments:POST only just added comment will be returned. Example: "comments": [ { "id": "515", "description": "<p>ghngfhnf<br />\n </p>", "description_processed": "<p>ghngfhnf<br />\n </p>", "created_by_id": "167", "created_ts": 1441478547, "likes_count": 2, "f_liked": true, "files": [{...}, {...}, ...], "can_edit": false }, ... ] PUT (actual request should be /comments/comment_id:POST) Input data: description - comment description. Can be empty or absent (equal to a comment containing an empty string). If you allow your users to edit comments you should be using description field not description_processed field. Field description_processed should not be exposed for editing directly as it does not contain meta-information required which may get erased and lead to some data loss if PUT back. Example: {"description": "sdkjcnsdcsdc sdc sdckjs dn"} Output: The same as for /comments:POST DELETE /comments/comment_id Deletes the comment. /users GET Input data: /users - returns all users visible to the current user /users/current - returns current user data /users/user_id - returns "users" array containing only specified user data, if the current user has permissions to see him. Empty "users" array otherwise Output: users: array with requested users data. Structure example: "users": { [ "user_id": "132942", "first_name": "f", "last_name": "", "avatar_url": "https:\\/\\/freedcamp-avatars-test.s3.amazonaws.com\\/4b322be59237277135526b97d1e86de2.jpg", "full_name": "f", "email": "bear@test.com", "timezone": "America/New_York" ], [ "user_id": "132944", "first_name": "fsdc", "last_name": "sdcd", "avatar_url": "https:\\/\\/freedcamp-avatars-test.s3.amazonaws.com\\/4b33322be59237277135526b97d1e86de2.jpg", "full_name": "f s.", "email": null, "timezone": "America/New_York" ], ... Note: "email" field is null if requesting user does not have permissions to see it. POST Input data: email, password, first_name, last_name, oauth_provider, oauth_id (inside the data), additional form FILE field - avatar file. name description email required password can be empty in a case when oauth_provider parameter is passed first_name required last_name can be empty oauth_provider if a user has done an unsuccessful login attempt using OAuth provider previously, an app may fill this field and oauth_access_token field with appropriate data to get user linked with the provider right after the registration. If OAuth provider has provided the app with email and first name, you can directly issue this request with an empty password (will be generated on the server side) without displaying a register screen to the user. Note that in case of returned errors (like empty email field) these errors will still correspond to register screen. A field can be empty or absent. oauth_access_token should be present if oauth_provider is set, can be empty or absent otherwise mobile_app_version a version of the mobile app As to the avatar attached - please note, the maximum available square portion of the image will be used as an avatar (will be used the central part of the image), and it will be resized to 100*100 px. X-API-TOKEN should be empty. Example: data: {"email": "bear+ss@deepshiftlabs.com", "password": "1111111111", "first_name": "fname", "last_name": "sdc"} avatar: binary file data* * i. e. request body contains 2 fields, string "data" and file "avatar", encoded as a form-data Output: the same as /sessions:POST returns PUT (actual request should be /users/current:POST) Input data: name description email can be empty or absent. If present and differes from the current one, confirmation_password should be passed. password SHOULD be empty or absent if user does not change it. If passed, confirmation_password should be passed also. first_name It can not be empty last_name It can be empty confirmation_password Active password should be passed only when email or/and password are changed timezone User's timezone. To get a list of available timezones, use /timezones:GET To update avatar, use /avatars/current:POST. Request data example: { "email": "some@freedcamp.com", "password": "", "first_name": "333", "last_name": "44444", "confirmation_password": "", "timezone": "America/New_York" } Output: the same as for /users/user_id:GET, also may contain token (see below). WARN! If email and/or password is changed, a user will be logged out from all devices, including the current one (current token becomes invalid). So if a token is returned in the response, an application SHOULD replace the old token with this new one. Output example with a token is below. When different tokens for different sessions are implemented, a token will not become obsolete. "data": { "users": [ {...} ], "token": "cc76fec61451717732153334d7e986acb380fcb2" }