---
title: "Create a project milestone"
method: POST
path: "/api/v2/project_milestones"
tags: ["Project Milestones"]
---

# Create a project milestone

`POST /api/v2/project_milestones`

## Request

- Base URL: `https://developer.productive.io` (the document declares no server; this is the origin it was published from)
- URL: `https://developer.productive.io/api/v2/project_milestones`
- Auth: none declared

Creates a milestone on a project. Requires `title`, `date`, `icon_id` and `project_id` — the project must be visible to you and cannot be a template. When `color_id` is omitted, the milestone takes the color of its project. `assignee_id` must be an active member of the project. Requires the permission to manage project milestones.

### Create a milestone

```json
{
  "data": {
    "type": "project_milestones",
    "attributes": {
      "title": "Beta launch",
      "date": "2026-10-15",
      "icon_id": "icon-rocket-launch",
      "note": "Release to beta customers.",
      "assignee_id": 1002,
      "project_id": 7388870
    }
  }
}
```

## Request body

- object: Request body for creating a project milestone.
  - `data` object: The JSON:API data object containing the project milestone attributes.
    - `attributes` object: Project milestone attributes.
      - `assignee_id` AssigneeId (unresolved $ref)
      - `color_id` ColorId (unresolved $ref)
      - `date` Date, required (unresolved $ref)
      - `icon_id` IconId, required (unresolved $ref)
      - `note` Note (unresolved $ref)
      - `project_id` ProjectId, required (unresolved $ref)
      - `title` Title, required (unresolved $ref)

## Response `201`

A single project milestone.

- object: A single project milestone record in JSON:API format.
  - `data` object: The JSON:API data object for the returned project milestone.
    - `attributes` object: Project milestone attributes.
      - `color_id` ColorId (unresolved $ref)
      - `created_at` CreatedAt (unresolved $ref)
      - `date` Date (unresolved $ref)
      - `icon_id` IconId (unresolved $ref)
      - `note` Note (unresolved $ref)
      - `title` Title (unresolved $ref)
      - `updated_at` UpdatedAt (unresolved $ref)
    - `relationships` object: Project milestone relationships.
      - `assignee` union: A JSON:API single relationship — links to one related resource or `null`.
        - SingleLinkageNullable
          - `data` Resource, required: A JSON:API resource identifier object containing the resource type and ID.
            - `id` string, required: The unique identifier of the resource.
            - `type` string, required: The resource type name (e.g. `tasks`, `people`, `deals`).
        - NotIncluded: Placeholder for a relationship that was not sideloaded in this response.
          - `meta` object, required: Metadata indicating the sideload status of this relationship.
            - `included` false, required: Whether the related resource was included in the sideloaded data. Always `false` for this variant.
      - `creator` union: A JSON:API single relationship — links to one related resource or `null`.
        - SingleLinkageNullable
          - `data` Resource, required: A JSON:API resource identifier object containing the resource type and ID.
            - `id` string, required: The unique identifier of the resource.
            - `type` string, required: The resource type name (e.g. `tasks`, `people`, `deals`).
        - NotIncluded: Placeholder for a relationship that was not sideloaded in this response.
          - `meta` object, required: Metadata indicating the sideload status of this relationship.
            - `included` false, required: Whether the related resource was included in the sideloaded data. Always `false` for this variant.
      - `organization` union: A JSON:API single relationship — links to one related resource or `null`.
        - SingleLinkageNullable
          - `data` Resource, required: A JSON:API resource identifier object containing the resource type and ID.
            - `id` string, required: The unique identifier of the resource.
            - `type` string, required: The resource type name (e.g. `tasks`, `people`, `deals`).
        - NotIncluded: Placeholder for a relationship that was not sideloaded in this response.
          - `meta` object, required: Metadata indicating the sideload status of this relationship.
            - `included` false, required: Whether the related resource was included in the sideloaded data. Always `false` for this variant.
      - `project` union: A JSON:API single relationship — links to one related resource or `null`.
        - SingleLinkageNullable
          - `data` Resource, required: A JSON:API resource identifier object containing the resource type and ID.
            - `id` string, required: The unique identifier of the resource.
            - `type` string, required: The resource type name (e.g. `tasks`, `people`, `deals`).
        - NotIncluded: Placeholder for a relationship that was not sideloaded in this response.
          - `meta` object, required: Metadata indicating the sideload status of this relationship.
            - `included` false, required: Whether the related resource was included in the sideloaded data. Always `false` for this variant.
  - `included` unknown[]: Sideloaded related resources.
    - unknown
  - `meta` Meta: Pagination and response metadata returned with every collection endpoint.
    - `current_page` integer: The current page number in this paginated response (1-based).
    - `max_page_size` integer: Maximum number of records allowed per page for this endpoint.
    - `organization_features` object: Feature flags and capabilities enabled for the current organization, used for UI rendering.
    - `page_size` integer: Number of records returned per page in this response.
    - `settings` object: Organization or user settings relevant to this resource's display.
    - `total_count` integer: Total number of records matching the current query across all pages.
    - `total_pages` integer: Total number of pages available for the current query and page size.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `406`: Not Acceptable
- `408`: Request Timeout
- `415`: Unsupported Media Type
- `422`: Unprocessable Content
- `423`: Locked
- `429`: Too Many Requests
- `500`: Internal Server Error

## Changes

- **2026-11-02** `fa3060fd0144`: 3 warning, 9 info
  - added the new `bad_decimal_format` enum value to the `errors/items/code` response property for the response status `422`
  - added the new `non_finite_number` enum value to the `errors/items/code` response property for the response status `422`
  - added the new `null_bytes_in_params` enum value to the `errors/items/code` response property for the response status `422`
  - added the non-success response with the status `400`
  - …8 more
- **2026-10-27** `f11a8740641a`: 1 info
  - endpoint added
  - …this revision’s changelog is incomplete

[Operation history](https://skmtc.dev/productive/apis/api-documentation/changes/api/v2/project_milestones/post.md)

---

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