Outlign

Outlign API

v1.0 Documentation

Tasks API

Manage tasks (also called "steps") within projects and phases. Tasks represent individual work items that can be assigned, tracked, and completed.

The Task Object

{
  "id": 123,
  "title": "Design homepage wireframe",
  "completed": false,
  "published": true,
  "due_date": "2023-02-15T00:00:00.000000Z",
  "created_at": "2023-01-01T12:00:00.000000Z",
  "updated_at": "2023-01-01T12:00:00.000000Z",
  "phase": { "id": 456, "title": "Design Phase", "is_internal": false },
  "project": { "id": 789, "title": "Website Redesign" },
  "client": { "id": 101, "title": "Acme Corporation" },
  "company": { "id": 202, "title": "Design Studio Inc" },
  "assignees": [ { "id": 3, "name": "Dave Prince" } ]
}

due_date is returned as an empty string ("") when the task has no due date. assignees is included in list responses; single-task responses (get / create / update) omit it — read or change assignees via the Task Assignees endpoints.

Attributes

Attribute Type Description
id integer Unique identifier for the task
title string The task's name
completed boolean Whether the task has been completed
due_date string Task due date (ISO 8601), or "" when not set
published boolean Whether the task is published (visible) within its phase
content string Task body as Markdown. Only returned when requested via ?include=content (see below)
phase object The phase the task belongs to (id, title, is_internal)
project object The project the task belongs to (id, title)
client object The client the task belongs to (id, title)
company object The agency company that owns the task (id, title)
assignees object[] Users assigned to the task (id, name). Managed via the Task Assignees endpoints

Including task content: The Markdown content field is opt-in for performance. Append ?include=content to a list or single-task request to have it returned. Without it, content is omitted from the response.

List Tasks

Retrieves a list of tasks the authenticated user has access to.

GET /api/v1/steps

Query Parameters

Parameter Type Description
company_id integer Filter tasks by specific company ID
completed boolean Filter by completion status
has_due_date boolean Filter tasks that have or don't have due dates
exclude_templates boolean Exclude tasks from template projects
include string Comma-separated extra fields to include. Use content to return each task's Markdown body.
per_page integer Number of results per page (max 1000)

Example Request

GET /api/v1/steps?completed=false&company_id=202&include=content&per_page=25
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

Example Response

[
  {
    "id": 123,
    "title": "Design homepage wireframe",
    "completed": false,
    "published": true,
    "due_date": "2023-02-15T00:00:00.000000Z",
    "created_at": "2023-01-01T12:00:00.000000Z",
    "updated_at": "2023-01-01T12:00:00.000000Z",
    "phase": { "id": 456, "title": "Design Phase", "is_internal": false },
    "project": { "id": 789, "title": "Website Redesign" },
    "client": { "id": 101, "title": "Acme Corporation" },
    "company": { "id": 202, "title": "Design Studio Inc" },
    "assignees": [ { "id": 3, "name": "Dave Prince" } ]
  }
]

Get a Task

Retrieves a specific task by ID.

GET /api/v1/steps/{id}

Example Request

GET /api/v1/steps/123
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

Example Response

{
  "id": 123,
  "title": "Design homepage wireframe",
  "completed": false,
  "published": true,
  "due_date": "2023-02-15T00:00:00.000000Z",
  "created_at": "2023-01-01T12:00:00.000000Z",
  "updated_at": "2023-01-01T12:00:00.000000Z",
  "phase": { "id": 456, "title": "Design Phase", "is_internal": false },
  "project": { "id": 789, "title": "Website Redesign" },
  "client": { "id": 101, "title": "Acme Corporation" },
  "company": { "id": 202, "title": "Design Studio Inc" }
}

Create a Task

Creates a new task within a phase.

POST /api/v1/steps

Request Body

Parameter Type Required Description
title string Yes The task's name
phase_id integer Yes ID of the phase this task belongs to
content string No Task content that will appear in the task details. Plain text is automatically converted to rich text format.
due_date string No Task due date (YYYY-MM-DD)
completed boolean No Whether the task is completed (defaults to false)

Example Request

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

{
  "title": "Create user flow diagram",
  "phase_id": 456,
  "content": "Design user flow for the new checkout process.\n\nInclude all edge cases and error states.",
  "due_date": "2023-02-20"
}

Example Response

{
  "id": 124,
  "title": "Create user flow diagram",
  "completed": false,
  "published": true,
  "due_date": "2023-02-20T00:00:00.000000Z",
  "created_at": "2023-01-15T10:00:00.000000Z",
  "updated_at": "2023-01-15T10:00:00.000000Z",
  "phase": { "id": 456, "title": "Design Phase", "is_internal": false },
  "project": { "id": 789, "title": "Website Redesign" },
  "client": { "id": 101, "title": "Acme Corporation" },
  "company": { "id": 202, "title": "Design Studio Inc" }
}

Update a Task

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

PUT /api/v1/steps/{id}

Request Body

Parameter Type Description
title string The task's name
content string Task content/description. Plain text is automatically converted to rich text format.
completed boolean Whether the task is completed
due_date string Task due date (YYYY-MM-DD)

Example Request

PUT /api/v1/steps/123
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
Accept: application/json

{
  "title": "Design homepage wireframe (Updated)",
  "content": "Updated requirements based on client feedback.",
  "completed": true,
  "due_date": "2023-02-18"
}

Example Response

{
  "id": 123,
  "title": "Design homepage wireframe (Updated)",
  "completed": true,
  "published": true,
  "due_date": "2023-02-18T00:00:00.000000Z",
  "created_at": "2023-01-01T12:00:00.000000Z",
  "updated_at": "2023-01-15T14:30:00.000000Z",
  "phase": { "id": 456, "title": "Design Phase", "is_internal": false },
  "project": { "id": 789, "title": "Website Redesign" },
  "client": { "id": 101, "title": "Acme Corporation" },
  "company": { "id": 202, "title": "Design Studio Inc" }
}

Delete a Task

Permanently deletes a task. Only company members can delete tasks.

DELETE /api/v1/steps/{id}

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

Example Request

DELETE /api/v1/steps/123
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

Example Response

204 No Content