Projects

The projects namespace provides API methods to retrieve all or specific projects a user has access to. This page covers the following API methods:

• GET /projects

• GET /projects/{project_id}

GET /projects

Returns all projects (a user has access to).

This method uses pagination so you might need to request additional pages to retrieve all projects.

Request

Parameters

page integer Number of page to return (default: first page)

per_page integer Maximum number of projects to return (supported: 15, 25, 50, 100; default: 100)

sort string Sort field for the list of projects (supported: projects:created_at, projects:completed_at; default: projects:created_at)

order string Sort order (ascending or descending) (supported: asc, desc; default: desc)

is_completed boolean Limit result to active or completed projects only.

expands string Comma-separated list of expands to return.

Schema

"page": {
    "type": "integer",
    "format": "int64",
    "description": "Number of page (default: first page)."
},
"per_page": {
    "type": "integer",
    "format": "int64",
    "enum": [
        15,
        25,
        50,
        100
    ],
    "description": "Maximum number of items to return per page (default: 100)."
},
"sort": {
    "type": "string",
    "enum": [
        "projects:created_at",
        "projects:completed_at"
    ],
    "description": "Sort field for the list of projects.",
},
"order": {
    "type": "string",
    "enum": [
        "asc",
        "desc"
    ],
    "description": "Sort order (ascending or descending)."
},
"is_completed": {
    "type": "boolean",
    "description": "Limit result to active or completed projects only."
},
"expands": {
    "type": "string",
    "description": "Comma-separated list of expands to return."
}

This method supports the following expands so you can automatically include additional information for referenced objects:

• users

Response

GET /api/v1/projects

200 OK
{
    "page": 1,
    "prev_page": null,
    "next_page": 2,
    "last_page": 2,
    "per_page": 100,
    "total": 150,
    "result": [
        {
            "id": 1,
            "name": "Spotlight",
            "note": null,
            "is_completed": true,
            "milestone_count": 10,
            "milestone_active_count": 3,
            "milestone_completed_count": 7,
            ..
            "created_at": "..",
            "created_by": 2,
            "updated_at": null,
            "updated_by": null,
            "completed_at": ".."
        },
        {
            "id": 2,
            "name": "Thunder",
            "note": null,
            "is_completed": false,
            "milestone_count": 10,
            "milestone_active_count": 3,
            "milestone_completed_count": 7,
            ..
            "created_at": "..",
            "created_by": 2,
            "updated_at": null,
            "updated_by": null,
            "completed_at": null
        },
        ..
    ],
    "expands": {
        ..
    }
}

Examples

// Get latest 100 projects
GET /api/v1/projects

// Get second result page (pagination)
GET /api/v1/projects?page=2

// Get latest 100 active projects
GET /api/v1/projects?is_completed=0

// Get latest 100 completed projects, ordered by completion date
GET /api/v1/projects?is_completed=1&sort=projects:completed_at

// Get projects and include user details
GET /api/v1/projects?expands=users

Status codes

200 400 401 422 (details)

GET /projects/{project_id}

Returns a single project (if the user has access to the project).

project_id id required ID of the project to return.

Request

Parameters

expands string Comma-separated list of expands to return.

Schema

"expands": {
    "type": "string",
    "description": "Comma-separated list of expands to return."
}

This method supports the following expands so you can automatically include additional information for referenced objects:

• users

Response

GET /api/v1/projects/1

200 OK
{
    "result": {
        "id": 1,
        "name": "Spotlight",
        "note": null,
        "is_completed": true,
        "milestone_count": 10,
        "milestone_active_count": 3,
        "milestone_completed_count": 7,
        ..
        "created_at": "..",
        "completed_at": "..",
    },
    "expands": {
        ..
    }
}

Examples

// Get the project with ID 5
GET /api/v1/projects/5

// Get a project and include user details
GET /api/v1/projects/1?expands=users

Status codes

200 400 401 404 422 (details)