Skip to main content

Projects

The projects namespace provides API methods to retrieve all or specific projects a user has access to, and to look up the workflow states and result statuses defined for a project. The following endpoints are available:

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
Schema

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 (supported: asc, desc; default: desc).
 

is_completed boolean
Limit results to active or completed projects only.
 

expands string
Comma-separated list of expands to return.
 

{
  "page": {
      "type": "integer",
      "format": "int64",
      "description": "Number of page to return (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"],
      "default": "projects:created_at",
      "description": "Sort field for the list of projects."
  },
  "order": {
      "type": "string",
      "enum": ["asc", "desc"],
      "default": "desc",
      "description": "Sort order (ascending or descending)."
  },
  "is_completed": {
      "type": "boolean",
      "description": "Limit results to active or completed projects only."
  },
  "expands": {
      "type": "string",
      "description": "Comma-separated list of expands to return (users)."
  }
}

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 429 (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
Schema

expands string
Comma-separated list of expands to return.
 

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

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)

GET /projects/{project_id}/states

Returns the list of workflow states for the specified project. States are returned for all three entity types — runs, repository cases, and sessions — in a single response, and each state includes an entity field identifying which it applies to. Use this endpoint to retrieve valid state IDs for use when creating or filtering runs, and when filtering repository cases or sessions.

project_id id required
ID of the project.
 

Response

Each state includes an entity field (run, repository_case, or session) identifying the resource type it applies to, and an is_default flag marking the default state for that entity type.

GET /api/v1/projects/1/states

 
200 OK
{
    "result": [
        {
            "id": 1,
            "entity": "run",
            "name": "Active",
            "is_default": true
        },
        {
            "id": 2,
            "entity": "run",
            "name": "In Review",
            "is_default": false
        },
        {
            "id": 5,
            "entity": "repository_case",
            "name": "Draft",
            "is_default": true
        },
        {
            "id": 6,
            "entity": "repository_case",
            "name": "Ready",
            "is_default": false
        },
        {
            "id": 9,
            "entity": "session",
            "name": "Open",
            "is_default": true
        }
    ]
}

State IDs from this endpoint are used by the Runs API (when creating or filtering runs) and by the Cases and Sessions APIs (when filtering by state).

Status codes

200 401 403 404 429 (details)

GET /projects/{project_id}/statuses

Returns the list of test result statuses assigned to the specified project, across all entity types (runs, sessions, and automation). Statuses are used when recording results for run tests. Each status indicates whether it is currently active — inactive statuses are retained for historical results but cannot be assigned to new results.

project_id id required
ID of the project.
 

Response

Each status includes an is_active flag (whether it can be assigned to new results) and an aliases array (alternative names accepted for the status, for example when submitting automation results). Inactive statuses are returned with "is_active": false.

GET /api/v1/projects/1/statuses

 
200 OK
{
    "result": [
        {
            "id": 1,
            "name": "Untested",
            "system_name": "untested",
            "color": "#aaaaaa",
            "is_active": true,
            "is_final": false,
            "is_untested": true,
            "is_passed": false,
            "is_failed": false,
            "aliases": []
        },
        {
            "id": 2,
            "name": "Passed",
            "system_name": "passed",
            "color": "#69aa1f",
            "is_active": true,
            "is_final": true,
            "is_untested": false,
            "is_passed": true,
            "is_failed": false,
            "aliases": ["pass", "ok"]
        },
        {
            "id": 3,
            "name": "Failed",
            "system_name": "failed",
            "color": "#c00000",
            "is_active": true,
            "is_final": true,
            "is_untested": false,
            "is_passed": false,
            "is_failed": true,
            "aliases": ["fail"]
        },
        {
            "id": 4,
            "name": "Retest",
            "system_name": "retest",
            "color": "#f0ad00",
            "is_active": true,
            "is_final": false,
            "is_untested": false,
            "is_passed": false,
            "is_failed": false,
            "aliases": []
        }
    ]
}

Status IDs from this endpoint are used when recording results through the Results API. Submitting a disabled (inactive) status is rejected.

Status codes

200 401 403 404 429 (details)

Was this article helpful?