---
agentTools:
  projectIndex: https://hubflo.readme.io/llms.txt
---

# Creates a task

Creates a task.
        To fill in a custom field, add the custom field 'serialization_name' to the request
        params, with the desired value. Only 100 tags maximum can be specified.
        When you specify a `parent_task_id` you will create a subtask. Some attributes are not available for subtasks:
        `clickup_id`, `monday_id`, `project_id` and `contact_id`.
        To attach a recurrence, set `recurrence_type` (`Weekly`, `Monthly`, `Yearly`, `Periodically`, `Custom`) along
        with the matching `recurrence_*` fields. `start_time` is required when a recurrence is set.
        For `Custom`, also provide `recurrence_frequency` and `recurrence_customable_type` (`Weekly` or `Monthly`)
        with the corresponding `recurrence_week_days` or `recurrence_day_into_month`.

# OpenAPI definition

````json
{
  "openapi": "3.0.1",
  "info": {
    "title": "Hubflo API",
    "version": "v2",
    "description": "The Hubflo API allows you to write and read data from the Hubflo application.\nIt conforms to [REST](https://en.wikipedia.org/wiki/REST).\nIt has predictable resource-oriented URLS, accepts JSON request bodies, returns JSON and uses standard HTTP status codes\nand verbs.\n\n# Authentication\n\nThe Hubflo API requires authentication.\nIt's a bearer authentication, also called token authentication.\n\nTo start your integration journey with the Hubflo API, you must send your **authentication token** in the\n`Authorization` header when making requests to the API.\n\n```\nAuthorization: Bearer <token>\n```\n\n# Getting started\n\nNavigate to [https://app.hubflo.com/organizations/](https://app.hubflo.com/organizations/).\nIn the **Integrations** settings panel, click on the **Generate key** button if you don't already have an API key.\n\nThe generated API key is the required authentication token you must send in the `Authorization` header.\nLet's copy it.\n\nYou can use the `/pings` endpoint to check that you can successfully make an authenticated request.\nDo it directly from this documentation, using the **Authorize** button to paste your authentication token, then push\nthe **Try it out** button.\n\nAlternatively, you can run the following cURL command in a terminal:\n\n```\ncurl -X 'POST' \\\n  'https://app.hubflo.com/api/v2/pings' \\\n  -H 'accept: application/json' \\\n  -H 'Authorization: Bearer <token>' \\\n  -d ''\n```\n\nIf you're successfully authenticated, you receive:\n\n```json\n{\n  \"pong\": \"ok\"\n}\n```\n\nOtherwise you get a `401 - Unauthorized` error. For example:\n\n```json\n{\n  \"status\": 401,\n  \"title\": \"Unauthorized\",\n  \"message\": \"API token not found\"\n}\n```\n\n# Versioning\n\nThe API is versioned. The current version is 2.0 (referenced as v2 in the endpoints).\n\n# Routes\n\nThe API endpoints are accessible through a route of the form: `https://<domain>/api/<version>/<endpoint>`.\n\nWhere:\n\n- `domain` is the domain to use, usually \"app.hubflo.com\"\n- `version` is the API version\n- `endpoint` is the endpoint name\n\nFor example, we will have: `https://app.hubflo.com/api/v2/pings`.\n\n# Request headers\n\nEvery request should include the header `Content-Type: application/json`, except for file uploads.\n\n# Requests and parameters\n\nThe API adheres to REST principles:\n\n- `GET` requests: read without modification\n- `POST` requests: create a new resource\n- `PATCH` requests: update an existing resource\n- `DELETE` requests: delete a resource\n\nThe parameters for `GET` requests should be sent via the query string of the request.\n\nThe parameters for `POST` and `PATCH` requests should be transmitted in the request body in a valid JSON format.\n\nThe parameters should follow the following formats:\n- `date`: \"YYYY-MM-DD\", for example: \"2021-10-21\"\n- `time`: \"H:m[:s]\", for example: \"10:30\"\n- `date-time`: \"YYYY-MM-DDThh:mm:ssZ\", which is the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations) format, using UTC\n\n# Response headers\n\nAs specified for each endpoint, the response headers contain:\n- `Content-Type`: the response content type\n- `X-Organization-ID`: your organization ID\n- `X-Rate-Limit` the maximum allowed requests in a given period\n- `X-Remaining-Requests`: the remaining requests count in the current period\n\n# Response format\n\nThe API only supports JSON format.\nAll responses sent by the API will contain the header `Content-Type: application/json` and their content is present in\nthe body in a JSON format to be de-serialized.\n\n# Rate limit\n\nThe use of the API is limited.\nYou can make a maximum of 1000 calls per minute.\nIf you exceed this limit, you receive a `429 - Too Many Requests` error and are blocked for one minute.\n\n# Pagination\n\nAll endpoints that return lists are paginated.\nIn general, any endpoint that returns a list can return an empty list.\n\nThe (optional) `page` parameter allows you to access a specific page.\n\nThe (optional) `per_page` parameter allows you to change the number of items on a given page.\nThe default value is 20 and it is limited to a maximum of 100.\n\n# Response codes\n\nThe API may return the following codes:\n\n| Code  | Name                  | Description                                                                      |\n| ----  | --------              | --------                                                                         |\n| `200` | Success               | Success                                                                          |\n| `201` | Created               | Resource created                                                                 |\n| `204` | No Content            | Success but the response does not contain any data (e.g., deletion)              |\n| `400` | Bad Request           | The request is invalid                                                           |\n| `401` | Unauthorized          | Authentication failed                                                            |\n| `403` | Forbidden             | Insufficient rights to perform the requested action                              |\n| `404` | Not Found             | The resource is not found                                                        |\n| `422` | Unprocessable Content  | The transmitted data is malformed                                                |\n| `429` | Too Many Requests     | Too many requests have been made                                                 |\n| `500` | Internal Server Error | An internal server error occurred (the technical team is automatically notified) |\n\n# Errors\n\nWhen an error occurs, the response code informs you about what is happening.\nThe response body contains:\n- the status code,\n- the status name, a.k.a the error title,\n- a human readable message.\n\nSee the error schemas below.\n\n# Resources\n\nAll resources are identified by a unique ID that looks like this: \"16242d6f-a808-41b7-8c4d-fe29b9b3245f\".\n\nJSON data types are used at most: `string`, `number`, `float`, `object`, `array`, `boolean` and `null`.\nDates and datetimes attributes are serialized with UTC [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations) format.\n\n\n"
  },
  "paths": {
    "/api/v2/tasks": {
      "post": {
        "summary": "Creates a task",
        "security": [
          {
            "bearer_auth": []
          }
        ],
        "description": "Creates a task.\n        To fill in a custom field, add the custom field 'serialization_name' to the request\n        params, with the desired value. Only 100 tags maximum can be specified.\n        When you specify a `parent_task_id` you will create a subtask. Some attributes are not available for subtasks:\n        `clickup_id`, `monday_id`, `project_id` and `contact_id`.\n        To attach a recurrence, set `recurrence_type` (`Weekly`, `Monthly`, `Yearly`, `Periodically`, `Custom`) along\n        with the matching `recurrence_*` fields. `start_time` is required when a recurrence is set.\n        For `Custom`, also provide `recurrence_frequency` and `recurrence_customable_type` (`Weekly` or `Monthly`)\n        with the corresponding `recurrence_week_days` or `recurrence_day_into_month`.",
        "tags": [
          "task"
        ],
        "parameters": [],
        "responses": {
          "201": {
            "description": "Task created",
            "headers": {
              "Content-Type": {
                "schema": {
                  "type": "string"
                },
                "description": "application/json; charset=utf-8"
              },
              "X-Organization-ID": {
                "schema": {
                  "type": "string"
                },
                "description": "The organization ID"
              },
              "X-Rate-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Max allowed requests in the current period"
              },
              "X-Remaining-Requests": {
                "schema": {
                  "type": "integer"
                },
                "description": "Remaining requests in the current period"
              }
            },
            "content": {
              "application/json": {
                "examples": {
                  "example": {
                    "value": {
                      "id": "4ef2557f-7e55-46e3-b9c0-58da9976acc9",
                      "name": "Task name",
                      "description": "Task description",
                      "completed": false,
                      "clickup_id": "123",
                      "monday_id": "123",
                      "kind": "to_do",
                      "visible_by_contact": true,
                      "slug": "4ef2557f-7e55-46e3-b9c0-58da9976acc9",
                      "created_at": "2026-11-17T16:33:03Z",
                      "creator_id": "70bab32c-8cde-4fd0-b73e-bab9fa61e3fc",
                      "creator_type": "User",
                      "start_time": "2021-01-01T00:00:00Z",
                      "end_time": "2021-01-01T00:15:00Z",
                      "contact_id": null,
                      "project_section_id": null,
                      "project_id": null,
                      "parent_task_id": null,
                      "workspace_id": null,
                      "tags": [],
                      "recurrence_type": null,
                      "recurrence_frequency": null,
                      "recurrence_customable_type": null,
                      "recurrence_week_days": null,
                      "recurrence_day_into_month": null,
                      "recurrence_days_after_completion": null
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "example": "Task name"
                  },
                  "description": {
                    "type": "string",
                    "example": "Task description"
                  },
                  "start_time": {
                    "type": "string",
                    "format": "date-time",
                    "example": "2021-01-01T00:00:00Z"
                  },
                  "completed": {
                    "type": "boolean",
                    "example": false
                  },
                  "clickup_id": {
                    "type": "string",
                    "example": "123"
                  },
                  "monday_id": {
                    "type": "string",
                    "example": "123"
                  },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "to_do",
                      "call",
                      "meeting",
                      "email",
                      "milestone"
                    ],
                    "example": "to_do"
                  },
                  "visible_by_contact": {
                    "type": "boolean",
                    "example": false
                  },
                  "template_id": {
                    "type": "string",
                    "example": "a0a0e818-749a-41d6-b898-43fa3ea55dd8",
                    "description": "ID of a task template to instantiate the task from. When provided, the task is created from the template (its name, description, assignments, tags, custom fields, files and subtasks are copied) and the template attributes take precedence over the other attributes."
                  },
                  "parent_task_id": {
                    "type": "string",
                    "example": "a0a0e818-749a-41d6-b898-43fa3ea55dd8"
                  },
                  "project_id": {
                    "type": "string",
                    "example": "a0a0e818-749a-41d6-b898-43fa3ea55dd8"
                  },
                  "project_section_id": {
                    "type": "string",
                    "example": "a0a0e818-749a-41d6-b898-43fa3ea55dd8",
                    "description": "Only project sections that are not templates can be used. Deprecated: attaching a task to a non-template project section is deprecated."
                  },
                  "contact_id": {
                    "type": "string",
                    "example": "a0a0e818-749a-41d6-b898-43fa3ea55dd8"
                  },
                  "workspace_id": {
                    "type": "string",
                    "example": "a0a0e818-749a-41d6-b898-43fa3ea55dd8",
                    "description": "Deprecated: attaching a task to a non-template workspace is deprecated."
                  },
                  "user_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "example": [
                      "a0a0e818-749a-41d6-b898-13fa3ea55dd8"
                    ]
                  },
                  "contact_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "example": [
                      "a0a0e818-749a-41d6-b898-13fa3ea55dd8"
                    ]
                  },
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "example": [
                      "tag1",
                      "tag2"
                    ]
                  },
                  "recurrence_type": {
                    "type": "string",
                    "nullable": true,
                    "enum": [
                      "Weekly",
                      "Monthly",
                      "Yearly",
                      "Periodically",
                      "Custom",
                      null
                    ],
                    "description": "Recurrence kind. Send `null` to remove an existing rule. Other\n`recurrence_*` attributes depend on this type.\n"
                  },
                  "recurrence_frequency": {
                    "type": "integer",
                    "nullable": true,
                    "example": 2
                  },
                  "recurrence_customable_type": {
                    "type": "string",
                    "nullable": true,
                    "enum": [
                      "Weekly",
                      "Monthly",
                      null
                    ]
                  },
                  "recurrence_week_days": {
                    "type": "array",
                    "nullable": true,
                    "items": {
                      "type": "string"
                    },
                    "example": [
                      "monday",
                      "friday"
                    ]
                  },
                  "recurrence_day_into_month": {
                    "type": "integer",
                    "nullable": true,
                    "example": 15
                  },
                  "recurrence_days_after_completion": {
                    "type": "integer",
                    "nullable": true,
                    "example": 7
                  }
                },
                "required": [
                  "name"
                ]
              }
            }
          },
          "required": true,
          "description": "Task attributes"
        }
      }
    }
  },
  "servers": [
    {
      "url": "https://app.hubflo.com",
      "description": "The production API server"
    },
    {
      "url": "https://staging.hubflo.com",
      "description": "The staging API server"
    },
    {
      "url": "http://localhost:3000",
      "description": "The local API server"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearer_auth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  },
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "_id": {
    "buffer": {
      "0": 102,
      "1": 23,
      "2": 174,
      "3": 218,
      "4": 191,
      "5": 119,
      "6": 176,
      "7": 0,
      "8": 103,
      "9": 211,
      "10": 245,
      "11": 119
    }
  }
}
````