Freedcamp Public API

תוכן

    Description

    This wiki describes Freedcamp public API things. 

    API end point: https://freedcamp.com/api/v1/.
    Postman collection which contains ready-to-go requests.
    Usage example (PHP).

    Setup

    To setup API for you please:

    1 - go to My Account/Integrations/API

    2 - generate a new API key

    3 - to access this page

    Authentification

    You may generate API keys on the Integrations/API tab on My Account page. There are two types of keys: secured by API secret and not secured (you may change the type when you want). We highly recommend to use Secured keys for your needs when possible, but for quick testing, you may want to omit additional security.

    Not secured API keys

    Just pass the api_key with the key value as a GET or POST parameter, for example:

    https:// freedcamp.com/api/v1/sessions/current?api_key=api_key

    Not secured API keys have expiration time in one week. This can be changed later.

    Note that anyone who has access to your active not secured API key can do most of the actions available via API. NEVER share unsecured API key with anyone. If you suspect a key leak, please convert the key to the secured with API secret or delete it. We'll forbid some types of actions (like project or account deletion) for not secured keys soon.

    Zapier API keys

    These keys are used for Zapier integration. These keys will only work for Zapier requests. Note that anyone who has access to your Zapier API key is also able to connect to your Freedcamp data with Zapier. These keys also have restricted permissions.

    Secured API keys

    To auth with these keys, except the key itself you need to also pass a timestamp and hash parameters. A timestamp is the request timestamp (check you have properly set time on your server), and a hash is calculated using API secret in this way (PHP code for example):

    $hash = hash_hmac('sha1', $api_key . $timestamp, $api_secret);

    So the request will look like:

    https:// freedcamp.com/api/v1/sessions/current?api_key=api_key&timestamp=current_ts&hash=your_hash

    Get your API secret on the API tab on My Account page (you will need to enter your password). NEVER share API secret with anyone and do not pass it publicly. Let us know if you suspect API secret key leak.
    Please check the "Calculating hash for secured API key" chapter below for more details.

    Passing API key in the header

    To not pass the API key as an URL parameter or inside POST body you may pass it via X-API-KEY header. This approach is used in requests in Postman collection.

    Other methods

    We plan to implement Oauth2 auth later on.

    Examples

    Postman collection which contains ready-to-go requests. Check "Setting up Postman" section below for details.
    Usage example (PHP).

    Request

    If a request should be done with any non-GET parameters (except auth parameters), it's supposed that they are passed as a form-data parameter with name 'data' and JSON-encoded value.

    Example:

    data: {"email": "test@email.com", "password": "11111111"}
    

    You may pass your auth credentials as POST data as well as in the GET with payload:

    api_key: api_key
    timestamp: current_ts
    hash: your_hash
    data: {"email": "test@email.com", "password": "11111111"}

    PUT requests

    All "update" requests which are described as PUT below should use POST requests. "Update" requests differ from "add" requests by passing id of the modified item. Later we may support PUT requests for updates.

    Response

    Each response returns JSON-encoded JS object with the following fields:

    name description
    http_code duplicates HTTP code passed in headers.
    msg 'OK' on successful request, an error description otherwise.
    error_id in the case when an error occurred and was logged by API, will contain corresponding error_id you can use to refer to in your support request to Freedcamp.
    maintenance (can be absent) in the case when there is active or upcoming Freedcamp maintenance scheduled (see Maintenance below).
    data specific for the request data, empty if an error happened or nothing to return. If there were some errors to show to a user, they will be placed under "errors" field. errors.general means some general error, errors._some_filed_name_ - means that error is for some posted field (like validation error).

    Examples of unsuccessful requests responses:

    {
      "http_code": 500,
      "msg": "Server error occurred.",
      "error_id": 1621951,
      "data": [errors: {"general": "Server error occurred, please try onу more time."}]
    }
    
    {
      "http_code": 401,
      "msg": "Wrong credentials",
      "error_id": 0,
      "data": []
    }
    
    {
      "http_code": 404,
      "msg": "Unknown method",
      "error_id": 0,
      "data": []
    }

    Maintenance

    When API endpoint is in the maintenance mode or there is upcoming maintenance, API, in addition to standard fields (msg, data, etc.), returns maintenance field on each request, which has the next fields:

    name description
    start_ts a timestamp of maintenance start
    duration the planned duration of the maintenance in minutes. A client should use it to inform users about planned time for service recovery ( which can be calculated as [start_ts + duration * 60]). The actual duration can be less than this value (if we finished maintenance sooner). Duration value may increase during the maintenance but has a low probability.
    msg a string with additional info for users about maintenance reasons. It can be empty. If it is not empty, should be shown somehow to the users in the client message about maintenance
    start_ts a timestamp of maintenance start
    duration the planned duration of the maintenance in minutes. A client should use it to inform users about planned time for service recovery ( which can be calculated as [start_ts + duration * 60]). The actual duration can be less than this value )if we finished maintenance sooner). Duration value may increase during the maintenance but has a low probability.

    Example:

      "maintenance": {
        "start_ts": 1479848400,
        "duration": 60,
        "msg": ""
      }

    Usually, maintenance field is being sent 60 minutes before the maintenance.

    If Freedcamp AOI endpoint is already in the maintenance mode, it returns HTTP 503 in headers (and still returns the maintenance field):

    {
      "http_code": 503,
      "msg": "Maintenance is in progress",
      "error_id": 0,
      "maintenance": {
        "start_ts": 1479848400,
        "duration": 60,
        "msg": ""
      },
      "data": {}
    }

    No actions were executed if API endpoint returned 503.

    A client should not send requests more often than one per minute while getting 503 in response.

    It's possible that web-interface is in maintenance mode and API endpoint is not and vice versa.

    Common filtration and ordering

    For some endpoints fetching the application items (like /tasks, /times, /issues, etc.) except the way described in the chapters, there is a hack - a quick way to get several filters combination for your API request:

    1. Open the application on freedcamp.com (web UI).
    2. Apply all needed filters and order.
    3. Copy url with applied filters:


    4. Extract GET parameters and add them to your API request:

    Supported methods

    /sessions

    Used to start a new session, get information about a current session or close a current session.
    Sessions are identified by a session token. Each device has own token with TTL of 1 week after the last action done in this session.
    If you have no active token when setting up the session, a new token will be created and returned, otherwise, the old one will be returned.

    GET

    Only /sessions/current will work.
    Returns the same data as POST request returns except for a token.

    POST

    WARNING: Is not supported now

    Returns session token and all info needed for the initial screen if valid email/password are passed. X-API-TOKEN should be empty. HTTP code 401 will be returned if a user can't be logged in using given credentials.

    Input data: email, password, oauth_provider, oauth_access_token

    name description
    email should be always present except when signing in via Twitter which does not provide us with user's email
    password user password, can be empty when using OAuth token to sign in
    oauth_provider for signing in by OAuth provider,  should contain provider unique name. Allowed names are "facebook", "linkedin", "google", "twitter". It can be empty or absent if signing in by email+password.
    oauth_access_token
    mobile_app_version a version of the mobile app.

    Output (inside 'data'):

    name description
    projects a list of all projects which user has access to.
    users a list of all users which current user can see in the projects he has access to. See structure example under /users request description.

    groups a list of all project groups which user has access to. Note that projects are ordered inside each group. To recreate projects order in projects dropdown in Web UI you should refer to groups list and projects list inside them. See structure example under /groups:GET request description.
    notifications_count unread notifications count
    token a session token to use further for API request inside headers
    user_id the user id of the session user

    Example of structure:

    "projects": [
          {
            "project_id": "914936",
            "role_name": "User",
            "role_type": "0",
            "project_name": "sdcscsdcscsdc",
            "project_description": "sdcsdcsdcsdcsdc",
            "project_color": "A86D54",
            "f_active": true,
            "project_unique_name": "by_api_6OI",
            "f_favorite": false,
            "f_can_delete": false,
            "f_can_manage": false,
            "f_can_leave": true,
            "notifications_count": 0,
            "users": [
              132942,
              309953,
              340312,
              377037,
              377039,
              377040
            ],
            "applications": [
                      6
                ]
            },
          "groups": [....],
          ...
       ]
    applications: (currently disabled) list of all Freedcamp applications. Structure example:
    "applications": [
          {
            "app_id": "1",
            "name": "Wall"
          },
          "2": {
            "app_id": "2",
            "name": "To-Do's"
          },
          ...
       ]

    DELETE

    WARNING: Is not supported now

    Only /sessions/current will work.

    Closes current session, and invalidates current session token (so all devices have to set up a new session again).

    /groups

    GET

    Output:  

    groups: array with available groups Structure example:

        groups": [
          {
            "group_id": "267229",
            "name": "groupNamenew",
            "description": "some descr",
            "group_unique_name": "as_9Ra",
            "projects": [
              "415078",
              "415079",
            ],
            "applications": [],
            "f_managed": true
          },
          {
            "group_id": "267230",
            "name": "fname's Projects",
            "description": "",
            "group_unique_name": "a12_3ec",
            "projects": [
              "415080"
            ],
            "applications": [],
            "f_managed": true
          },
          ...
    

    f_managed: user can create projects or move them only into managed groups

    /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

    /invitations

    GET

    /invitations - returns the list of all user's pending invitations to projects. Each element contains group_name, project_name, hash, and invited_by_user fields. 

    invited_by_user has the same structure as user array structure returned by /users:GET request. Note that email is always NULL. 

    The API endpoint returns extended data (instead of just project_id and invited_by_id) as a user is not yet a part of any project. Information for such invited user can't be obtained by standard /projects and /users requests.

    Example:

    "invitations": [
          {
            "group_name": "Some group",
            "project_name": "Some project",
            "hash": "f543a44968d5214c7511e071be0f6ec4",
            "invited_by_user": {
              "user_id": "1231122",
              "first_name": "bear_d",
              "last_name": "",
              "avatar_url": "http://some_url",
              "full_name": "bear_d",
              "email": null,
              "timezone": "Europe/Athens"
            }
          }
        ]

    PUT

    (actual request should be /invitations:POST)

    Input data: an array of objects with hash and action keys

    name description
    hash  invitation hash you get by /invitations:GET
    action  what to do with the invitation. Possible actions are 'accept' and 'decline'.

    Request data example:

    {
    	"invitations": [{
    		"hash": "bc4fcff30a99d7524ef36855a95f54a8",
    		"action": "accept"
    	}, {
    		"hash": "aaafcff30a99d7524ebbb855a95f54a8",
    		"action": "decline"
    	}]
    }

    Output: the same as for /invitations:GET

    /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"
      }

    DELETE

    See /wipe for user deletion.

    /wipe

    /wipe/current

    GET

    WARN: Not allowed publicly, for now,

    is used to get information about the account before deleting it. Currently, it returns the only flag f_password_needed.

    Output data:

    name description
    f_password_needed true or false. Not active or accounts created recently can be deleted w/o password confirmation, so you should check f_password_needed and do not ask the user for a password confirmation if it's false.

    Output example:

      "data": {
        "f_password_needed": true
      }

    POST

    WARN: Not allowed publicly for now

    is used to delete a user account and all linked data

    Input data:

    name description
    password  confirmation password. It can be empty or absent if f_password_needed returned by /wipe:GET is false

    Input example:

        {"password": "11111111"}
    
    

    /password_reset_emails

    POST

    If successful, an email to the given email will be sent with the reset key inside which should be used in /passwords:POST request then

    Input data: email

    Example:

    {"email": "xxx@xxxxx.com"}

    Output (inside 'data'):

    msg: Message you may show to the user, like "Reset key has been sent to xxx@xxx.com"

    /passwords

    Allows to set a new password using reset password key sent by issuing /password_reset_emails:POST request

    POST

    Input data:

    password: new password.

    name description
    reset_key password reset key from the email

    Example:

    {"password": "11111111", "reset_key": "xxx"}
    

    /avatars

    POST

    I plan to use only POST requests for all actions related to files uploading because of PUT limitations in PHP when working with files. That's why avatar update is not under the /users/current:PUT request.

    Input data: 

    form FILE field - binary avatar file (not inside the data parameter with JSON)

    example:

    avatar: binary file data*

    * request body should be encoded as a form-data

    Output:

    avatar: an object which contains a new avatar URL. Example:

        "avatar": {
          "avatar_url": "https:\\/\\/freedcamp-avatars-test.s3.amazonaws.com\\/4b322be59235557135526b97d1e86de2.jpg"
        }
    

    DELETE

    Use /avatars/current to reset the avatar to a default generated an image.

    Output: the same as for /avatars/current:POST.

    /notifications

    GET

    /notifications - returns "notifications" array inside data for all projects.
    WARN! - can be slow, please avoid to call it too often.

    /notifications/project_id - returns "notifications" array inside data for given project id.

    Filtration

    By default, you get all notifications or all unread notifications in the project. To get unread notifications only for the items you are following (equal to "Things I follow" filter in web UI), pass a following=1 parameter:

    /notifications?following=1 or /notifications/project_id?following=1.

    Output:

    notifications: Array of items with unread actions for the specified project. Read notifications are considered to be added later. Example:

        "notifications": [
              {
                "project_id": "344",
                "item_u_key": "267220_415075_2_488",
                "app_id": "2",
                "item_id": "488",
                "item_title": "sdfvsdvsdvf",
                "f_read": false,
                "last_action_ts": 1438178379,
                "actions": [
                  {
                    "description_raw": "bear2 b. added todo.",
                    "description": "bear2 b. added todo.",
                    "action_ts": 1439569606,
                    "action_type": 1
                  }
                ]
              },
              {
                "project_id": "344",
                "item_u_key": "267220_415075_2_487",
                "app_id": "2",
                "item_id": "487",
                "item_title": "tergertg",
                "f_read": false,
                "last_action_ts": 1438178379,
                "actions": [
                  {
                    "description_raw": "bear2 b. <p>said</p>: фscasdc<br />\n",
                    "description": "bear2 b. said: фscasdc\n ",
                    "action_ts": 1439569566,
                    "action_type": 9
                  },
                  {
                    "description_raw": "bearr s. added todo.",
                    "description": "bearr s. added todo.",
                    "action_ts": 1439551062,
                    "action_type": 1
                  }
                ]
    name description
    project_id project id of notification
    item_u_key id for item notifications, use it for "mark as read" request
    f_read  is always true as now we return only unread notifications
    last_action_ts used for setting item as read to determine if a user has seen the actual version
    actions  an array of actions, more recent actions first. "description_raw" may contain HTML tags, they are stripped in "description" field.
    action_type see types list in the Constants wiki

    PUT

    (actual request should be /notifications:POST)

    Input data: 

    name description
    new_state  new state of notifications, possible values - read
    items  an array of items to apply the state to.

    Structure of items array:
    item_u_key 
    last_action_ts

    Request data example:

    {
    	"new_state": "read",
    	"items": [{
    		"item_u_key": "267200_415044_2_2034232",
    		"last_action_ts": "425235345"
    	}]
    }

    /validations

    GET

    /notifications/email - checks if email used for an invitation is valid and does not exist in the project, also returns avatar URL if check passed. Probably these actions will be split/moved to different API URLs after discussions.

    "email" in URL means a type of validation. 

    Input:

    name description
    email email to validate
    project_id optional. If set, an output will contain an error if the email is already present in the project users

    Request example: 

        data:   {"email": "", "project_id": "423242"}

    Output:

    avatar_url - on success

    Example:

        "avatar_url": "https://freedcamp-avatars-test.s3.amazonaws.com/534d29407bfce199827779dbb4b4a3c8e_6eabef.png"

    /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.

    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 if task_group_name is passed
    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
    item_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.

    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.

    item_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

    /milestones

    GET

    /milestones- returns a list of all milestones user has access to

    /milestones?project_id=xxx - list of milestones in the project

    /milestones/milestone_id - list of milestones which contains only the milestone with given milestone_id 

    Limits

    All /milestones:GET requests support limit and offset parameters. Example: "/milestones?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.

    Example

    To fetch all the milestones, you need to execute a set of requests like

    https://freedcamp.com/api/v1/milestones?limit=200&offset=0
    https://freedcamp.com/api/v1/milestones?limit=200&offset=200
    https://freedcamp.com/api/v1/milestones?limit=200&offset=400
    ....

    while there are results or meta.has_more is true.

    Filtration and order

    If you need more filters and orders please contact support.

    Output example for /milestones:GET:

    Output:

    milestones: list of milestones with the next fields:

    name description
    id milestone id
    project_id
    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 milestone by id) processed description, where [fcattach] tags are replaced with actual images with link. WARN - is present only when you request only one milestone, absent otherwise. You should show to user this data when showing milestone (and use raw "description" when editing).
    assigned_to_id user id milestone is assigned to. May have values -1 (ASSIGNED_EVERYONE) and 0 (ASSIGNED_NOONE).
    created_by_id user id who created the milestone.
    created_ts
    updated_ts
    due_ts
    start_ts null if it was not set.
    status One of the next values: 0 (not started), 1 (completed), 2 (in progress). See also 'priority_title' field and constants wiki.
    priority possible values: 0 (none), 1 (low), 2 (medium), 3 (high).
    f_archived false if the milestone is active, true if the milestone is archived.
    assigned_to_fullname name of a user milestone is assigned to.
    order set by user order (using d&d). By default milestones in output are ordered by this field.

    WARN! It's possible that several milestones inside the same group have the same order value including default value (0).

    WARN! This field is NOT equal to the milestone position in the returned list.

    comments_count
    linked_items (absent if it's not a get milestone by id) array of tasks milestone is linked to. Tasks structure is described above.
    comments  (absent if it's not a get milestone by id) list of comments. Comments structure is described above.
    files (absent if it's not a get milestone by id) files attached to the milestone (files attached to milestone comments are not counted).
    followers (absent if it's not a get milestone by id) array of user ids subscribed to milestone.
    app_id APP_MILESTONES (4)

    Example:

            "milestones": [
                {
                    "id": "318",
                    "project_id": "561",
                    "title": "[318] Milestone to test followers",
                    "description": "<p>qweqweqweqe</p>\n",
                    "description_processed": "<p>qweqweqweqe</p>\n",
                    "assigned_to_id": "281",
                    "created_by_id": "189",
                    "created_ts": 1614696522,
                    "updated_ts": 1617888076,
                    "due_ts": 1617138000,
                    "start_ts": 1614636000,
                    "status": 2,
                    "priority": 3,
                    "f_archived": false,
                    "assigned_to_fullname": "Kate I.",
                    "order": 0,
                    "comments_count": 1,
                    "linked_items": [{...}, {...}, ...],
                    "comments": [{...}, {...}, ...],
                    "files": [{...}, {...}, ...],
                    "followers": [
                        "189",
                        "202",
                        "211",
                        "283",
                        "281",
                        "157"
                    ],
                    "app_id": "4"
                }
            ]

    Comments structure: the same as /comments:POST returns.

    POST

    Input data: 

    name description
    title
    description  can be an empty string
    project_id
    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).
    due_date  the format is YYYY-MM-DD
    attached_ids  an array of files uploaded previously with temporary=1 flag

    Request example:

    {"project_id":"561", "title":"ms title","description":"<p>descr...</p>\n","start_date":"2021-04-05","due_date":"2021-04-11","priority":1,"assigned_to_id":"-1","attached_ids":["2233"]}

    Output: the same as /milestones/milestone_id:GET

    PUT

    (actual request should be /milestones/milestone_id:POST)

    Input data: 

    The same set as for /milestones:POST. You may pass only changed parameters as well and skip passing not changed.

    Request data example:

    {"title":"ms title","description":"<p>descr...</p>\n","start_date":"2021-04-05","due_date":"2021-04-14","priority":2,"assigned_to_id":"157","status":0}

    Output: the same as /milestones/milestone_id:GET

    DELETE

    /milestones/milestone_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

    /timezones

    GET

    /timezones - returns all available timezones. You should use one of the ids to update user's timezone trough /users/current:PUT.

    curr_offset field respects DST for a timezone.

    Output:

    see example:

    "timezones": [
        {
            "id": "Europe/Prague",
            "title": "UTC+01:00 Prague, Warsaw",
            "curr_offset": 120,
            "curr_time": "20:11"
        },
        {
            "id": "Europe/Athens",
            "title": "UTC+02:00 Athens, Helsinki, Istanbul",
            "curr_offset": 180,
            "curr_time": "21:11"
        },
        ....
    ]
    

    /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.

    /issues

    GET

    /issues - returns a list of all issues user has access to

    /issues/?project_id=xxx - list of issues in the project

    /issues/issue_id - list of issues which contains only the issue with given issue_id

    Limits

    All /issues:GET requests support limit and offset parameters. Example: "/issues?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 than there were returned in the response, and false otherwise.
    total_count presents if show_more = true and contains all available results.

    Filtration and order

    /issues and /issues/?project_id=xxx requests support filtration and ordering. Filters/order can be applied in any combination.

    Supported filters:

    name description
    type possible values are: "Bug", "Cosmetics", "Exception", "Feature", "Task", "Usability", "Performance", "Auto-Reported". For example, to get only Features, you should use:  "/issues?type[]=feature"
    priority possible values are: 1, 2, 3. For example, to get only high priority issues, you should use:  "/issues?priority[]=3"
    status possible values are: 0, 1, 2, 3, 4 ("Open", "Completed", "InProgress", "Invalid", "Review"). For example, to get only open and invalid issues, you should use:  "/issues?status[]=0&status[]=3"
    assigned_to_id accepts integer values containing user id or one of Assignments constants from constants wiki
    due_date[to] accepts a date in format YYYY-MM-DD. If set, only issues with the due date set and due date <= due_date[to] will be returned
    due_date[from] accepts a date in format YYYY-MM-DD. If set, only issues with the due date set and due date >= due_date[from] will be returned

    Supported orders: 

    due_date: issues 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.

    If not valid filter or order value is passed, this value is ignored and the throttle penalty may be applied.

    Example: /issues?type[]=feature&priority[]=3&status[]=0&due_date[from]=2018-09-01&due_date[to]=2018-09-28&assigned_to_id[]=13&assigned_to_id[]=-1&assigned_to_id[]=0&order[due_date]=asc

    Output example for /issues:GET:

    Output:

    issues: list of issues with the next fields:

    name description
    id issue id
    project_id
    title
    number_prefixed auto-generated number of the issue with project prefix, like "COP-1001"
    description raw description, with Freedcamp tags
    description_processed (absent if it's not a get one issue by id) processed description, where [fcattach] tags are replaced with actual images with a link. WARN - is present only when you request only one issue, absent otherwise. You should show to a user this data when showing the issue (and use raw "description" when editing).
    created_by_id user id who created the issue
    assigned_by_email If an issue is created using a public widget, contains the email used in it
    assigned_to_id user id issue is assigned to. May have value 0 (ASSIGNED_NOONE).
    comments_count
    order set by user order

    WARN! It's possible that several issues have the same order value including default value (0).

    WARN! This field is NOT equal to the issue position in the returned list.

    status possible values: 0 (Open), 1 (Completed), 2 (InProgress), 3 (Invalid), 4 (Review). See also 'status_title' field and constants wiki
    priority possible values: 1 (low), 2 (medium), 3 (high). See also 'priority_title' field and constants wiki
    type possible values: "Bug", "Cosmetics", "Exception", "Feature", "Task", "Usability", "Performance", "Auto-Reported"
    created_ts
    closed_by_id user_id of the user who closed the issue
    closer_id user_id of the user who will close the issue
    completed_ts if was completed, ts when it happened, null otherwise
    due_ts null if was not set
    status_title
    priority_title
    assigned_to_fullname name of the user the issue is assigned to
    created_by_fullname name of the user who created the issue
    comments  (absent if it's not a get issue by id) list of comments. Comments structure: the same as /comments:POST returns.
    files (absent if it's not a get issue by id) list of files attached to the issue. See /files:GET for structure description
    app_id APP_BUGTRACKER (13)

    Example:

        "issues": [
                {
                    "id": "147",
                    "project_id": "561",
                    "title": "By API",
                    "number_prefixed": "REC-1013",
                    "description": "by api",
                    "description_processed": "by api",
                    "created_by_id": "189",
                    "assigned_by_email": "",
                    "assigned_to_id": "189",
                    "comments_count": 0,
                    "order": 0,
                    "status": 3,
                    "priority": 2,
                    "type": "Bug",
                    "created_ts": 1555933097,
                    "closed_by_id": "189",
                    "closer_id": "189",
                    "completed_ts": null,
                    "due_ts": 1440712800,
                    "status_title": "Invalid",
                    "priority_title": "Medium",
                    "assigned_to_fullname": "Kateryna Iakubovska",
                    "created_by_fullname": "Kateryna Iakubovska",
                    "comments": {},
                    "files": {},
                    "app_id": "13"
                },
          ...
        ]

    POST

    Input data: 

    name description
    title
    description can be an empty string
    project_id
    priority possible values: 1 (low), 2 (medium), 3 (high). See also 'priority_title' field and constants wiki
    status possible values: 0 (Open), 1 (Completed), 2 (InProgress), 3 (Invalid), 4 (Review). See also 'status_title' field and constants wiki
    type possible values: "Bug", "Cosmetics", "Exception", "Feature", "Task", "Usability", "Performance", "Auto-Reported"
    assigned_to_id user id issue is assigned to. May have value 0 (ASSIGNED_NOONE).
    due_date can be empty or absent, the format is YYYY-MM-DD
    closer_id user_id of the user who will close the issue
    attached_ids an array of files uploaded previously with temporary=1 flag

    Request example:

    {"title": "New issue", "description": "by api", "project_id": "561", "priority": 2, "status": 0, "type": "Bug", "assigned_to_id": "189", "due_date": "2019-05-01", "closer_id": "189", "attached_ids":[1296, 1297]} 
    

    Output: the same as /issues/issue_id:GET

    PUT

    (actual request should be /issues/issue_id:POST)

    Input data: 

    The same set as for /issues:POST. You may pass only changed parameters as well and skip passing not changed.

    Request data example:

    {"title": "Edited issue", "description": "by api (edited)", "project_id": "561", "priority": 1, "status": 3, "type": "Bug", "assigned_to_id": "189", "due_date": "2019-04-25", "closer_id": "189", "attached_ids":[1296, 1297]}

    Output: the same as /issues/issue_id:GET

    DELETE

    /issues/issue_id:DELETE

    /times

    GET

    /times - returns a list of all time records user has access to

    /times?project_id=xxx - returns a list of time records in the project

    /times/time_id - returns a list of time records which contains only the event with given event_id

    Limits

    All /times:GET requests support limit and offset parameters. Example: "/times?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.

    Filtration and order

    /times and /times?project_id=xxx requests support filtration and ordering. Filters/order can be applied in any combination.

    Supported filters:

    name description
    assigned_to_id accepts integer values containing user id or one of Assignments constants from constants wiki.
    date[from] accepts a date in format YYYY-MM-DD. If set, only time records with the date set date >= due_date[from] will be returned.
    date[to] accepts a date in format YYYY-MM-DD. If set, only time records with the date set and <= due_date[to] will be returned.

    Supported orders: 

    date - orders by the time record date

    WARN: if there are many orders in the request, only the first one will be applied.

    If not valid filter or order value is passed, this value is ignored.

    Example: /times?date[from]=2018-03-01&date[to]=2018-04-01&assigned_to_id[]=13&assigned_to_id[]=-1&order[date]=asc

    Output

    name description
    id
    project_id
    created_by_id  user id who created the record
    assigned_to_id  user id who is linked to the record
    description  description
    date_ts  selected date
    status one of the next values: 0 (not started), 1 (completed), 2 (in progress)
    minutes_count  how many minutes was worked
    created_ts  when the time record was created
    started_ts  if time record is started (i.e. timer is running), contains start timestamp. The current timer value is automatically added to the minutes_count field.
    app_id APP_TIME (5)

    Example:

    "times": [
        {
            "id": "79",
            "project_id": "547",
            "created_by_id": "167",
            "assigned_to_id": "-1",
            "description": "4",
            "date_ts": 1521244800,
            "status": 0,
            "minutes_count": 1,
            "created_ts": 1521174531,
            "started_ts": null
        },
        {
            "id": "81",
            "project_id": "547",
            "created_by_id": "167",
            "assigned_to_id": "167",
            "description": "assigned me",
            "date_ts": 1522195200,
            "status": 1,
            "minutes_count": 15,
            "created_ts": 1522131399,
            "started_ts": null
        },
        {
            "id": "83",
            "project_id": "547",
            "created_by_id": "167",
            "assigned_to_id": "-1",
            "description": "assigned everyone",
            "date_ts": 1522368000,
            "status": 2,
            "minutes_count": 0,
            "created_ts": 1522131439,
            "started_ts": null
        }
    ]

    POST

    Input data: 

    name description
    description
    project_id
    assigned_to_id should contain assigned to user id OR constant: -1 (ASSIGNED_EVERYONE)
    date selected date, required, format is YYYY-MM-DD
    minutes_count how many minutes was worked
    status one of the next values: 0 (not started), 1 (completed), 2 (in progress)

    Request example:

    {"project_id": "561", "description": "New time record", "assigned_to_id": "189", "date": "2019-04-19", "minutes_count": 20, "status":1} 
    

    Time record can be linked to a task, 'link_item_id' (task id to link) and 'link_app_id' ('2' for Tasks application) fields should be added to POST data for this.

    Example:

    {"project_id": "561", "description": "New time record linked to a task", "assigned_to_id": "189", "date": "2019-04-19", "minutes_count": 20, "status":1,"link_app_id":"2","link_item_id":"33008"}

    Output: the same as /times/time_id:GET

    PUT

    (actual request should be /times/time_id:POST)

    API supports property editing or actions. If there is a non-empty action field in POST, we handle action command execution, else - process property changes.

    Input data (property editing): 

    The same set as for /times:POST, except f_started, f_billed and project_id. You may pass only changed parameters as well and skip passing not changed.

    Request data example:

    {"description": "Edited time record", "assigned_to_id": "-1", "date": "2019-04-20", "minutes_count": "0"}

    Output: the same as /times/time_id:GET

    Input data (actions): 

    Possible actions

    name description
    start starts time tracking for a time record. UI action: 'Start working'
    stop stops time tracking for a time record. Value from a timer is adding to a time record time value. UI action: 'Stop working'
    bill makes a time record billed, billed time record cannot be started and stopped. UI action: 'Mark as Completed'
    unbill returns a time record to progress, start and stop become available. User interface action is 'Back in Progress'

    Request data example:

    {"action": "stop"}

    Output: the same as /times/time_id:GET

    DELETE

    /times/time_id:DELETE

    /calendar_items

    GET

    /calendar_items - returns a list of all calendar items user has access to (grouped by applications)

    /calendar_items?project_id=xxx - returns a list of calendar items in the project (grouped by applications)

    Output structure example:

    {
        "http_code": 200,
        "msg": "OK",
        "error_id": 0,
        "data": {
            "tasks": [{...}, ... {...}],
            "milestones": [{...}, ... {...}],
            "issues": [{...}, ... {...}],
            "events": [{...}, ... {...}],
            "crm_calls": [{...}, ... {...}],
            "crm_tasks": [{...}, ... {...}]
        }
    }
    

    /events

    GET

    /events - returns a list of all calendar events user has access to

    /events?project_id=xxx - returns a list of calendar events in the project

    /events/event_id - returns a list of events that contains only the event with given event_id

    The default period for returned events data is the current month (Dec 1 - Dec 31 if today is Dec, 8th). To modify this period you can use parameters 'from_ts' and 'to_ts' (UNIX timestamp). You can pass one or both at the same time.

    Examples:

    /events?from_ts=1639574817&to_ts=1643673600
    /events?project_id=xxx&to_ts=1643673600

    Limits

    All /events:GET requests support limit and offset parameters. Example: "/events?limit=2&offset=2".

    Output:

    events: list of calendar events with the next fields:

    name description
    id event id
    project_id
    title
    description
    created_by_id user id who created the task
    due_ts timestamp, an alias for end_ts 
    start_ts timestamp, start date and time
    end_ts timestamp, end date and time
    root_start_ts timestamp, start date and time of the first occurrence if the event is recurring or an alias for start_ts if the event is not recurring
    root_end_ts timestamp, end date and time of the first occurrence if the event is recurring or an alias for start_ts if the event is not recurring
    duration in minutes
    f_all_day true if the event has start and end time or false if the event is all day long
    r_rule empty if the event is not recurring
    url URL for the event
    app_id APP_CALENDAR (19)

    Example:

            "events": [
                {
                    "id": "1301",
                    "project_id": "561",
                    "title": "last day of the month",
                    "description": "",
                    "created_by_id": "189",
                    "due_ts": 1553983200,
                    "date_start": 1553983200,
                    "date_end": 1553983200,
                    "duration": 120,
                    "f_all_day": false,
                    "r_rule": "RRULE:FREQ=MONTHLY;BYMONTHDAY=-1;UNTIL=20200101T000000",
                    "url": "/Calendar_Events_Grou_Cm9/Recurring_Tasks_kpi/calendar/1301",
                    "app_id": "19"
                },
                {
                    "id": "1303",
                    "project_id": "561",
                    "title": "31",
                    "description": "",
                    "created_by_id": "189",
                    "due_ts": 1553983200,
                    "date_start": 1553983200,
                    "date_end": 1553983200,
                    "duration": 1440,
                    "f_all_day": true,
                    "r_rule": "RRULE:FREQ=MONTHLY;BYMONTHDAY=31;UNTIL=20200101T000000",
                    "url": "/Calendar_Events_Grou_Cm9/Recurring_Tasks_kpi/calendar/1303",
                    "app_id": "19"
                },
            ]
    

    POST

    Input data: 

    name description
    title
    description  can be an empty string
    project_id
    f_all_day empty if a new event has a start and end time, 1 - if a new event is all day long
    date_start required, the format is YYYY-MM-DD, must be earlier or equal to the date_end
    time_start required if f_all_day is empty, final start date and time must be earlier or equal to the final end date and time
    date_end  required, the format is YYYY-MM-DD
    time_end required if f_all_day is empty, final start date and time must be earlier or equal to the final end date and time
    r_rule  the recurrence rule in iCalendar (RFC 5545) format. Empty if the event is not repeating.
    attached_ids  an array of files uploaded previously with temporary=1 flag
    mixed_users  an array of invited user ids or/and emails of not registered users

    Request example:

    {"project_id": "561","title":"new recurring event","description":"event example","f_all_day":true,"date_start":"2019-04-01","time_start":"14:00:00","date_end":"2019-04-01","time_end":"14:30:00","r_rule":"RRULE:FREQ=DAILY;COUNT=5","attached_ids":[1296, 1297],"mixed_users":["189","katya+tt@freedcamp.com","425"]}

    Output: the same as /events/event_id:GET

    PUT

    (actual request should be /events/event_id:POST)

    Input data: 

    The same set as for /events:POST. You may pass only changed parameters as well and skip passing not changed.

    Request data example:

    {"title":"edited recurring event","description":"event example","f_all_day":false,"date_start":"2019-04-01","time_start":"14:00:00","date_end":"2019-04-01","time_end":"14:30:00","r_rule":"RRULE:FREQ=DAILY;COUNT=5","attached_ids":""}

    Output: the same as /events/event_id:GET

    DELETE

    /events/event_id:DELETE

    /lists

    Supported applications are: Tasks, Wiki, Discussions, Passwords, Files.

    GET

    GET /lists/app_id?project_id=xxx - returns all active lists for a given application in the project.

    GET /lists/app_id - returns all active lists for a given application in all projects, ordered by Project Group order ASC, Project order ASC, List order ASC. Is supported only for Tasks.

    app_id stands for the integer application id (check the constants wiki). Supported apps are APP_TODOS, APP_FILES, APP_DISCUSSIONS, APP_WIKI, APP_PASSMAN.

    Output:

    lists: array of requested lists with the next fields

    name description
    id list id
    title
    description
    order order of the list inside the project, starting from 0
    project_id
    app_id Application id (wiki). Supported apps are APP_TODOS, APP_FILES, APP_DISCUSSIONS, APP_WIKI, APP_PASSMAN.

    Example: 

            "lists": [
                {
                    "id": "1409",
                    "name": "tasks for archived ms",
                    "title": "tasks for archived ms",
                    "description": "",
                    "order": 0,
                    "project_id": "561",
                    "app_id": "2"
                },
                {
                    "id": "1408",
                    "name": "subtasks",
                    "title": "subtasks",
                    "description": "",
                    "order": 1,
                    "project_id": "561",
                    "app_id": "2"
                }
            ]

    POST

    Input data: 

    name description
    title required
    description can be an empty or omitted
    project_id required
    h_parent_id only for APP_FILES, used in folders hierarchy. If passed and value is greater than 0 - new subfolder will be created for folder_id = h_parent_id

    Request example:

    POST /lists/2  // Tasks

    data: {"project_id": "561", "title": "List by API", "description": "by api"}
    

    POST /lists/6  // Files

    data: {"project_id": "561", "title": "List by API", "h_parent_id": 14}

    Output: the same as /lists/app_id:GET but 'lists' array contains the just created list only.

    PUT

    (actual request should be /list/app_id/list_id:POST)

    Input data: 

    The same set as for /lists:POST except the project_id. You may pass only changed parameters and skip passing not changed.

    Request data example:

    data: {"title": "List by API", "description": "by api"}

    Output: the same as /lists/app_id:GET but 'lists' array contains the just updated list only.

    DELETE

    WARN: Not allowed publicly for now

    DELETE /lists/app_id/list_id

    Deletes the list.

    /favorite_projects

    POST

    /favorite_projects/project_id

    Sets a project as a favorite.

    DELETE

    /favorite_projects/project_id

    Sets a project as not favorite.

    /backups

    GET

    /backups returns all existing backups.

    Limits

    /backups:GET request supports limit and offset parameters. Example: "/backups?limit=2&offset=2". Current default (and maximum allowed) limit for public API is 200. Backups are ordered by date created DESC, so the most recent backups are on top. It's recommended to use reasonable limit to get only last backups, like limit=20.

    All responses contain "meta" field:

        "meta": {
            "has_more": true, // always presents
            "total_count": 120 // presents if has_more = true
        }

    has_more is true if there are more results than were returned in the response, and false otherwise.
    total_count presents if show_more = true and contains all available results count.

    Output

    name description
    id
    date_human
    url Authorized S3 URL, expires in 24 hours

    Example:

    "backups": [
        {
            "id": "23422",
            "date_human": "Oct 2, 2018",
            "url": "https://s3.amazonaws.com/backup_2342222_2018-10-02_0102.zip?AWSAccessKeyId=JNKJCDNSSDCDCSD&Expires=12143242432&Signature=qqT%2Bey2zW%2B0%2tOC6J2W8i1bN%2BpmI%3D"
        },
        ...
        {
            "id": "23410",
            "date_human": "Jul 1, 2018",
            "url": "https://s3.amazonaws.com/backup_2342342_2018-07-01_0102.zip?AWSAccessKeyId=JNKJCDNSSDCDCSD&Expires=12143242432&Signature=qqT%2Bey2zW%2B0%2tOC6J2W8i1bN%2BpmI%3D"
        }
    ]

    Calculating hash for a secured API key

    Validation tool

    Simple&rude html page where you can check if your hash is properly calculated (opens in a new tab).

    Javascript

    var secret = 'your secret API key';
    var public_key = 'your secured public api key';
    var ts = new Date().valueOf();
    var hash = CryptoJS.HmacSHA1(public_key + ts, secret);
    var hash_string = hash.toString(); // send this to API

    C#

    The code below is kindly provided by Freedcamp user H. Gokhan Mamaci:

    private static readonly Encoding encoding = Encoding.UTF8;
    void Main()
    {
       var key_public = "your secured public api key";
       var key_private = "your secret API key";
       var ts = UnixTimeStampTotalSeconds();
       var keyByte = encoding.GetBytes(key_private);
    
       using (var hmacsha1 = new HMACSHA1(keyByte))
       {
             hmacsha1.ComputeHash(encoding.GetBytes(string.Concat(key_public, ts)));
             var hashstr = ByteToString(hmacsha1.Hash);
             $"https://freedcamp.com/api/v1/sessions/current?api_key={key_public}&timestamp={ts}&hash={hashstr}".Dump();
       }
    }
    
    static string ByteToString(byte[] buff)
    {
       string sbinary = "";
       for (int i = 0; i < buff.Length; i++)
           sbinary += buff[i].ToString("x2");
       return sbinary;
    }
    
    static string UnixTimeStampTotalSeconds()
    {
       DateTime nx = new DateTime(1970, 1, 1); // UNIX epoch date
       TimeSpan ts = DateTime.UtcNow - nx;
       return ((long)ts.TotalSeconds).ToString();
    }
    

    Setting up Postman

    Postman will allow you to easily check and test all the available methods. Note that not all methods in the collection are currently allowed for access through public API (like /wipe).
    To get requests working for the example collection, you need to define 'xapikey' variable in the current Postman environment with the value of your api_key. No need to define cookie and xapitoken variables so far.
    For a simple start you may use not-secured api_key - it does not require calculating hash.

    If you want to use API key secured with API secret, you should define a pre-request script which will calculate hash based on the current time. You should end up having set up like shown below.

    Url

    {{apihost}}/api/v1/tasks?api_key={{public_api_key}}&timestamp={{timestamp}}&hash={{hash}}&limit=5&offset=0

    Pre-request script

    var public_api_key = "your api key";
    var secret_key = "your api secret";
    var timestamp = Math.floor(new Date().valueOf()/1000);
    
    var hash = CryptoJS.HmacSHA1(public_api_key + timestamp, secret_key);
    
    // lines below will be a bit different for the standalone version - you'll use pm.environment.set("public_api_key", public_api_key);
    postman.setEnvironmentVariable("public_api_key", public_api_key);
    postman.setEnvironmentVariable("timestamp", timestamp);
    postman.setEnvironmentVariable("hash", hash.toString());

    Examples

    Attaching files to tasks

    There are two possible ways to attach a file to a task: 

    1) Create a task. Now upload a file with "temporary=0" field and with proper values for project_id, app_id ('2' for Tasks) and item_id (i.e. task id).

    curl -X POST \
      http://freedcamp.bear.com/api/v1/files?api_key=your_api_key \
      -H 'Content-Type: application/x-www-form-urlencoded' \
      -H 'cache-control: no-cache' \
      -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
      -F 'data={"project_id": "632", "application_id": "2", "item_id": "323", "comment_id": "", "temporary":0}' \
      -F 'file=@C:\file.txt'

    2) Upload file(s) with "temporary=1" field and remember their id (returned in the response). You also need to set application_id and project_id.

    curl -X POST \
      http://freedcamp.bear.com/api/v1/files?api_key=your_api_key \
      -H 'Content-Type: application/x-www-form-urlencoded' \
      -H 'cache-control: no-cache' \
      -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
      -F 'data={"project_id": "632", "application_id": "2", "item_id": "", "comment_id": "", "temporary":1}' \
      -F 'file=@C:\file.txt'

    Returned file id = 1748. Now post a task, passing these id(s) in attached_ids field:

    curl -X POST \
      http://freedcamp.bear.com/api/v1/tasks?api_key=your_api_key \
      -H 'cache-control: no-cache' \
      -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
      -F 'data={"title": "33333", "description": "wwwwwww", "project_id": "632", "task_group_id": "2599259", "task_group_name": "","task_group_description": "", "priority": "1", "assigned_to_id": "167", "due_date": "2015-08-28", "attached_ids":[1748]}'

    Questions and bug reports

    Please send your questions and bug reports to help@freedcamp.com

    Feature requests

    Please post your feature requests on Freedcamp's UserVoice portal

    Found 1 of matches