Outlign

Outlign API

v1.0 Documentation

Milestones API

Manage milestones within projects and phases. Milestones represent key dates and deliverables that help track progress across your projects.

The Milestone Object

{
  "id": 42,
  "title": "Design Review",
  "description": "Final design review with stakeholders",
  "color": "#9177FB",
  "due_date": "2023-03-15T00:00:00.000000Z",
  "is_completed": false,
  "milestoneable_type": "App\\Models\\Project",
  "milestoneable_id": 789,
  "project": {
    "id": 789,
    "title": "Website Redesign"
  },
  "client": {
    "id": 101,
    "title": "Acme Corporation"
  },
  "company": {
    "id": 202,
    "title": "Design Studio Inc"
  },
  "created_at": "2023-01-01T12:00:00.000000Z",
  "updated_at": "2023-01-01T12:00:00.000000Z"
}

Attributes

Attribute Type Description
id integer Unique identifier for the milestone
title string The milestone's name
description string Detailed description of the milestone (nullable)
color string Color for milestone visualization (nullable)
due_date string Milestone due date (ISO 8601 format)
is_completed boolean Whether the milestone has been completed
milestoneable_type string The type of entity the milestone belongs to (App\Models\Project or App\Models\Phase)
milestoneable_id integer ID of the project or phase this milestone belongs to
project object The resolved project object (derived from the milestone's parent)
client object The resolved client object (derived from the project's client)
company object The resolved company object (derived from the client's company)
created_at string ISO 8601 timestamp when the milestone was created
updated_at string ISO 8601 timestamp when the milestone was last updated

Polymorphic Relationship

Milestones use a polymorphic relationship and can be attached to either a Project or a Phase. The milestoneable_type and milestoneable_id fields together define the parent entity.

Project Milestone

  • • milestoneable_type: "App\Models\Project"
  • • milestoneable_id: The project ID
  • • Tracks project-level deadlines

Phase Milestone

  • • milestoneable_type: "App\Models\Phase"
  • • milestoneable_id: The phase ID
  • • Tracks phase-level deadlines

List Milestones

Retrieves a list of milestones the authenticated user has access to, ordered by due date.

GET /api/v1/milestones

Query Parameters

Parameter Type Description
company_id integer Filter milestones by specific company ID
project_id integer Filter milestones by specific project ID (includes both direct project milestones and milestones on the project's phases)
per_page integer Number of results per page (max 1000)

Example Request

GET /api/v1/milestones?project_id=789&per_page=25
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

Example Response

{
  "data": [
    {
      "id": 42,
      "title": "Design Review",
      "description": "Final design review with stakeholders",
      "color": "#9177FB",
      "due_date": "2023-03-15T00:00:00.000000Z",
      "is_completed": false,
      "milestoneable_type": "App\\Models\\Project",
      "milestoneable_id": 789,
      "project": {
        "id": 789,
        "title": "Website Redesign"
      },
      "client": {
        "id": 101,
        "title": "Acme Corporation"
      },
      "company": {
        "id": 202,
        "title": "Design Studio Inc"
      },
      "created_at": "2023-01-01T12:00:00.000000Z",
      "updated_at": "2023-01-01T12:00:00.000000Z"
    }
  ]
}

Get a Milestone

Retrieves a specific milestone by ID.

GET /api/v1/milestones/{id}

Example Request

GET /api/v1/milestones/42
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

Example Response

{
  "id": 42,
  "title": "Design Review",
  "description": "Final design review with stakeholders",
  "color": "#9177FB",
  "due_date": "2023-03-15T00:00:00.000000Z",
  "is_completed": false,
  "milestoneable_type": "App\\Models\\Project",
  "milestoneable_id": 789,
  "project": {
    "id": 789,
    "title": "Website Redesign"
  },
  "client": {
    "id": 101,
    "title": "Acme Corporation"
  },
  "company": {
    "id": 202,
    "title": "Design Studio Inc"
  },
  "created_at": "2023-01-01T12:00:00.000000Z",
  "updated_at": "2023-01-01T12:00:00.000000Z"
}

Create a Milestone

Creates a new milestone on a project or phase.

POST /api/v1/milestones

Request Body

Parameter Type Required Description
title string Yes The milestone's name (max 255 chars)
due_date string Yes Milestone due date (YYYY-MM-DD format)
milestoneable_type string Yes The parent type: App\Models\Project or App\Models\Phase
milestoneable_id integer Yes ID of the project or phase
description string No Detailed description of the milestone
color string No Color for visualization (e.g., "#9177FB")
is_completed boolean No Whether the milestone is completed (defaults to false)

Example Request

POST /api/v1/milestones
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
Accept: application/json

{
  "title": "Design Review",
  "due_date": "2023-03-15",
  "milestoneable_type": "App\\Models\\Project",
  "milestoneable_id": 789,
  "description": "Final design review with stakeholders",
  "color": "#9177FB"
}

Example Response

{
  "id": 42,
  "title": "Design Review",
  "description": "Final design review with stakeholders",
  "color": "#9177FB",
  "due_date": "2023-03-15T00:00:00.000000Z",
  "is_completed": false,
  "milestoneable_type": "App\\Models\\Project",
  "milestoneable_id": 789,
  "project": {
    "id": 789,
    "title": "Website Redesign"
  },
  "client": {
    "id": 101,
    "title": "Acme Corporation"
  },
  "company": {
    "id": 202,
    "title": "Design Studio Inc"
  },
  "created_at": "2023-01-15T10:00:00.000000Z",
  "updated_at": "2023-01-15T10:00:00.000000Z"
}

Update a Milestone

Updates an existing milestone's information, including marking it as completed.

PUT /api/v1/milestones/{id}

Request Body

Parameter Type Description
title string The milestone's name (max 255 chars)
due_date string Milestone due date (YYYY-MM-DD format)
description string Detailed description of the milestone
color string Color for visualization
is_completed boolean Whether the milestone is completed

Example Request

PUT /api/v1/milestones/42
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
Accept: application/json

{
  "title": "Design Review (Final)",
  "is_completed": true
}

Example Response

{
  "id": 42,
  "title": "Design Review (Final)",
  "description": "Final design review with stakeholders",
  "color": "#9177FB",
  "due_date": "2023-03-15T00:00:00.000000Z",
  "is_completed": true,
  "milestoneable_type": "App\\Models\\Project",
  "milestoneable_id": 789,
  "project": {
    "id": 789,
    "title": "Website Redesign"
  },
  "client": {
    "id": 101,
    "title": "Acme Corporation"
  },
  "company": {
    "id": 202,
    "title": "Design Studio Inc"
  },
  "created_at": "2023-01-01T12:00:00.000000Z",
  "updated_at": "2023-01-15T14:30:00.000000Z"
}

Delete a Milestone

Permanently deletes a milestone. This action cannot be undone.

DELETE /api/v1/milestones/{id}

Warning: Deleting a milestone will permanently remove it and cannot be undone. Consider marking milestones as completed instead of deleting them to maintain project history.

Example Request

DELETE /api/v1/milestones/42
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

Example Response

204 No Content