---
title: "Create a Goal"
method: POST
path: "/goals"
tags: ["goals"]
---

# Create a Goal

`POST /goals`

## Request

- Base URL: `https://localhost:8080/api/v9`
- URL: `https://localhost:8080/api/v9/goals`
- Auth: HTTP basic
- TypeScript: <https://skmtc.dev/toggl/apis/toggl-api/docs/goals/post.ts> (a function with typed inputs; its response is checked against the schema)

Create a Goal object with its parameters.
`goal_type` field must contain either `projects` or `billable` object, not both, or `null` if the goal
has `workspace` type.

## Request body

- ModelsPlainGoal
  - `archived` boolean
  - `archived_at` string
  - `cadence_period` string
  - `comparing` string
  - `current_cadence` ModelsGoalCadence
    - `achieved` boolean
    - `cadence_end` string
    - `cadence_start` string
    - `goal_cadence_id` integer
    - `goal_parameter_id` integer
    - `streak` integer
    - `tracked_value` integer
  - `description` string
  - `end` string
  - `goal_id` integer
  - `goal_parameter_id` integer
  - `goal_type` ModelsGoalType
    - `billable` boolean: For simplicity's sake we will not use GoalBillableType here
    - `projects` ModelsGoalProjectType[]
      - `project_id` integer
      - `task_id` integer
  - `icon` integer
  - `icon_color` string
  - `name` string
  - `start` string
  - `target_value` integer
  - `type_name` string
  - `user_id` integer
  - `workspace_id` integer

## Response `200`

Created Goal with its ID

- GoalsParamsCreate
  - `cadence_period` string, required
  - `comparing` string, required
  - `description` string
  - `end` string
  - `goal_type` ModelsGoalType, required
    - `billable` boolean: For simplicity's sake we will not use GoalBillableType here
    - `projects` ModelsGoalProjectType[]
      - `project_id` integer
      - `task_id` integer
  - `icon` integer
  - `icon_color` string
  - `name` string, required
  - `start` string, required
  - `target_value` integer, required
  - `workspace_id` integer, required

## Other responses

- `400`: Some required parameter was not filled, have invalid format or goals limit was reached
- `403`: User doesn't belong to given workspace, project or task. It also fails if project or task don't belong to workspace
- `500`: Internal Server Error

---

[API](https://skmtc.dev/toggl/apis/toggl-api.md) - [All operations](https://skmtc.dev/toggl/apis/toggl-api/llms.txt) - [OpenAPI document](https://skmtc.dev/toggl/apis/toggl-api/revisions/3085aee16990?raw)