> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.coperniq.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.coperniq.io/_mcp/server. # List Projects GET https://api.coperniq.io/v1/projects Retrieve a paginated list of projects. Supports: * Pagination (`page_size`, `page`) * Date filtering (`updated_after`, `updated_before`, optionally widened to project-level line item edits via `include_line_item_updates`) * Phase entry/exit date filtering (`entered_phase_id`+`entered_after`/`entered_before`, `exited_phase_id`+`exited_after`/`exited_before`) * Sorting (`order_by`) * Field search (`title`, `address`, `primaryName`, `primaryPhone`, `primaryEmail`) * Full text search (`q`) **Note:** `updated_after`/`updated_before` also match projects whose custom property values changed within the window. **Note:** If a project has no `title` (empty or whitespace-only), the response returns the parent account's `title` instead. The stored value is not modified — this is a read-time fallback only. Title-based search (`title` query param, full-text `q`, or the `/projects/search` endpoint with `prop=title&op=contains`) also matches projects whose own title is null/empty when the parent account's title matches the search term. **Note:** `entered_phase_id`/`exited_phase_id` identify a phase *template* (shared across all projects on a workflow), not a specific phase instance. Use the `phaseTemplateId` from a `GET /projects/{project_id}` response to find the id for a given phase. When either filter is used, each row also includes a compact `phaseTimeline` (`phaseTemplateId`, `startedAt`, `completedAt`); use `GET /projects/{project_id}` for the full `phaseInstances` with names/positions/SLA. Reference: https://docs.coperniq.io/api-reference/projects/list-projects ## Authentication - `x-api-key` header (required) — API Key authentication via header ## Request ### Query parameters - `page_size` (integer, optional, default: 20) — Number of items per page (max 100) - `page` (integer, optional, default: 1) — Page number (1-based) - `updated_after` (ProjectsGetParametersUpdatedAfter, optional) — Filter items updated after this timestamp (ISO 8601). Also matches records whose custom property values changed within the window. - `updated_before` (ProjectsGetParametersUpdatedBefore, optional) — Filter items updated before this timestamp (ISO 8601). Also matches records whose custom property values changed within the window. - `include_line_item_updates` (boolean, optional, default: false) — Requires `updated_after` and/or `updated_before` to also be passed — has no effect on its own. When true, widens that window to also match projects whose project-level line items (estimate/scope items) were added or edited in the window, and adds a `lineItemsUpdatedAt` field to each returned project (the most recent `updatedAt` among its own scope line items, `null` if none). Line items on quotes/invoices are excluded. Deletions and reorders are not detected. Ordering remains on the project's own updatedAt, so this flag is not a replacement for a full change-feed. Default: false. Only applies to project list/search endpoints. - `entered_phase_id` (integer, optional) — Phase template ID to filter by phase-entry date. Required when `entered_after` or `entered_before` is provided. Given alone (no date bounds), matches records that ever entered this phase. - `entered_after` (string, optional) — Only include records that entered the phase given by `entered_phase_id` on or after this date/timestamp. Accepts a date (`2026-07-01`) or a full ISO 8601 timestamp (`2026-07-01T00:00:00Z`). Requires `entered_phase_id`. - `entered_before` (string, optional) — Only include records that entered the phase given by `entered_phase_id` before this date/timestamp (exclusive). Accepts a date (`2026-08-01`) or a full ISO 8601 timestamp (`2026-08-01T00:00:00Z`). Requires `entered_phase_id`. - `exited_phase_id` (integer, optional) — Phase template ID to filter by phase-exit date. Required when `exited_after` or `exited_before` is provided. Given alone (no date bounds), matches records that have exited this phase at any point. - `exited_after` (string, optional) — Only include records that exited the phase given by `exited_phase_id` on or after this date/timestamp. Accepts a date (`2026-07-01`) or a full ISO 8601 timestamp (`2026-07-01T00:00:00Z`). Requires `exited_phase_id`. - `exited_before` (string, optional) — Only include records that exited the phase given by `exited_phase_id` before this date/timestamp (exclusive). Accepts a date (`2026-08-01`) or a full ISO 8601 timestamp (`2026-08-01T00:00:00Z`). Requires `exited_phase_id`. On opportunities, combine with `exited_phase_id` set to a "Closed - Won"-style phase template to find deals that closed within a date range. - `order_by` (enum, optional, default: asc) — Sort order for results - Allowed values: `asc`, `desc` - `include_virtual_properties` (boolean, optional, default: false) — Whether to include virtual properties in the response. Defaults to false unless explicitly set to true. - `include_archived` (boolean, optional, default: false) — Whether to include archived (inactive) records in the response. By default only active records are returned. - `include_contacts` (boolean, optional, default: false) — Whether to include associated contacts in the response. Defaults to false unless explicitly set to true. - `q` (string, optional) — Full text search query - `title` (string, optional) — Title search query - `address` (string, optional) — Address search query - `primaryName` (string, optional) — Contact name search query - `primaryPhone` (string, optional) — Contact phone search query - `primaryEmail` (string, optional) — Contact email search query ## Response ### 200 List of projects - `list of Project` ## Errors ### 400 Bad Request Error Invalid request - `message` (string, optional) - `code` (enum, optional) - Allowed values: `UNAUTHORIZED` - `field` (string, optional) — Field that caused the validation error (if applicable) ### 401 Unauthorized Error Authentication failed - `message` (string, optional) - `code` (enum, optional) - Allowed values: `UNAUTHORIZED` ## Types ### ProjectsGetParametersUpdatedAfter ### ProjectsGetParametersUpdatedBefore ### Project - `id` (integer, optional) — Unique identifier - `createdAt` (string, optional) — Creation timestamp - `updatedAt` (string, optional) — Timestamp of the most recent update to the record, including changes to its custom property values. - `title` (string, optional) — Record title/name - `description` (string, optional, nullable) — Record description - `address` (list of string, optional) — Record location/address - `isActive` (boolean, optional) — Whether the record is active - `primaryEmail` (string, optional, nullable) — Primary contact email - `primaryPhone` (string, optional, nullable) — Primary contact phone - `number` (integer, optional) — Record number (e.g., 1234) - `createdBy` (UserSummary, optional, nullable) — User who created the record. Null when the record was created by a non-user actor (e.g. automation or a contact). - `updatedBy` (UserSummary, optional, nullable) — User who last edited a field on the record, derived from the changelog. Null when the record has never been edited or the last edit was made by a non-user actor. - `custom` (map from string to any, optional) — Custom fields - `trades` (list of enum, optional) — Array of trade types - Allowed values: `EV Charger`, `Solar`, `Storage`, `Boiler`, `Chiller`, `Ductwork`, `HVAC`, `Refrigeration`, `Electrical`, `Generator`, `Lighting`, `Gas Line`, `Plumbing`, `Water Filtration`, `Water Heater`, `Communications`, `Electronic Safety & Security`, `Integrated Automation`, `Insulation`, `Gutters`, `Roofing`, `Siding`, `Windows`, `Drywall`, `General Contracting`, `Home Improvement`, `Landscaping`, `R&R (Remove & Reinstall)`, `Tenant Improvement`, `Tree Cutting` - `value` (double, optional, nullable) — Project value - `size` (double, optional, nullable) — Project size - `workflowId` (integer, optional, nullable) — Associated workflow ID - `accountId` (integer, optional, nullable) — Associated account ID - `status` (enum, optional) — Status of the project: * `ACTIVE` - Project is active and in progress * `ON_HOLD` - Project is temporarily paused * `CANCELLED` - Project has been cancelled * `COMPLETED` - Project has been completed - Allowed values: `ACTIVE`, `ON_HOLD`, `CANCELLED`, `COMPLETED` - `stage` (ProjectStage, optional) — Current stage information (Workflows 1.0). This object is present only for records still using the original Stage-based workflow engine. When the project is managed by Workflows 2.0 (Phase engine) the `stage` object and related fields (`stageId`, `timeInStageDays`, `slaStatus`) are omitted. - `phase` (ProjectPhase, optional) — Current phase information (Workflows 2.0). This object replaces `stage` when a project is attached to the Phase-based workflow engine. If the project is still on Workflows 1.0 this object will be omitted. Only populated on GET (list, search, get by id) — omitted on create/update responses. - `phaseTimeline` (list of ProjectPhaseTimelineItems, optional) — Only present on `GET /projects` and `/projects/search` when `entered_phase_id`/`exited_phase_id` is used to filter the results. Contains the project's full phase-transition history (not just the matched phase) in compact form — use `GET /projects/{project_id}` for the complete `phaseInstances` with names, positions, and SLA info. - `lineItemsUpdatedAt` (string, optional, nullable) — Only present on `GET /projects` and `/projects/search` when `include_line_item_updates=true` is passed together with `updated_after` and/or `updated_before`. The most recent `updatedAt` among the project's own scope line items (estimate/scope items; line items on quotes/invoices are excluded). `null` if the project has no scope line items. Useful for telling whether a row matched the date window via its own `updatedAt` or via a line item edit. - `workflowName` (string, optional) — Name of the associated workflow. - `contacts` (list of ContactRef, optional) — Contacts associated with this project (independent of, and not inherited from, the parent account's contacts). Set on create or update via the `contacts` request field. On GET requests, only populated when include_contacts=true is passed. Always populated on POST (create) and PATCH (update) responses. Ordered with the primary contact first, capped at 20 contacts. ### UserSummary Minimal user representation used in responses - `id` (integer, optional) - `firstName` (string, optional, nullable) - `lastName` (string, optional, nullable) - `email` (string, optional, nullable) - `avatarUrl` (string, optional, nullable) ### ProjectStage Current stage information (Workflows 1.0). This object is present only for records still using the original Stage-based workflow engine. When the project is managed by Workflows 2.0 (Phase engine) the `stage` object and related fields (`stageId`, `timeInStageDays`, `slaStatus`) are omitted. - `id` (integer, optional) — Stage identifier - `name` (string, optional) — Stage name - `type` (string, optional) — Stage type - `scope` (string, optional) — Stage scope - `redSla` (integer, optional) — Red SLA threshold in days - `yellowSla` (integer, optional) — Yellow SLA threshold in days - `timeInStageDays` (integer, optional) — Number of days in current stage - `slaStatus` (enum, optional) — Current SLA violation status - Allowed values: `VIOLATED`, `NON_VIOLATED` ### ProjectPhase Current phase information (Workflows 2.0). This object replaces `stage` when a project is attached to the Phase-based workflow engine. If the project is still on Workflows 1.0 this object will be omitted. Only populated on GET (list, search, get by id) — omitted on create/update responses. - `instanceId` (integer, optional) — Phase instance identifier - `templateId` (integer, optional) — Phase template identifier - `name` (string, optional) — Phase name - `status` (string, optional) — Current phase status - `type` (string, optional) — Phase type - `redSla` (integer, optional) — Red SLA threshold in days (from template) - `yellowSla` (integer, optional) — Yellow SLA threshold in days (from template) - `timeInStageDays` (integer, optional) — Number of days in current phase (mirrors `timeInStageDays` metric) - `slaStatus` (enum, optional) — Current SLA violation status for the phase - Allowed values: `VIOLATED`, `NON_VIOLATED` ### ProjectPhaseTimelineItems - `phaseTemplateId` (integer, optional) - `startedAt` (string, optional, nullable) — Timestamp when the project entered this phase template - `completedAt` (string, optional, nullable) — Timestamp when the project exited this phase template ### ContactRef - `id` (integer, optional) - `name` (string, optional) - `title` (string, optional, nullable) — Contact title (e.g. job title) - `description` (string, optional, nullable) - `emails` (list of string, optional) - `phones` (list of string, optional) - `isPrimary` (boolean, optional) — True for the primary contact (the first contact in the list). At most one contact is primary. ## Examples **Response** ```json [ { "id": 1, "createdAt": "2024-01-15T09:30:00Z", "updatedAt": "2024-01-15T09:30:00Z", "title": "string", "description": "string", "address": [ "string" ], "isActive": true, "primaryEmail": "string", "primaryPhone": "string", "number": 1, "createdBy": { "id": 1, "firstName": "string", "lastName": "string", "email": "string", "avatarUrl": "string" }, "updatedBy": { "id": 1, "firstName": "string", "lastName": "string", "email": "string", "avatarUrl": "string" }, "custom": {}, "trades": [ "EV Charger" ], "value": 1.1, "size": 1.1, "workflowId": 1, "accountId": 1, "status": "ACTIVE", "stage": { "id": 1, "name": "string", "type": "string", "scope": "string", "redSla": 1, "yellowSla": 1, "timeInStageDays": 1, "slaStatus": "VIOLATED" }, "phase": { "instanceId": 1, "templateId": 1, "name": "string", "status": "string", "type": "string", "redSla": 1, "yellowSla": 1, "timeInStageDays": 1, "slaStatus": "VIOLATED" }, "phaseTimeline": [ { "phaseTemplateId": 1, "startedAt": "2024-01-15T09:30:00Z", "completedAt": "2024-01-15T09:30:00Z" } ], "lineItemsUpdatedAt": "2024-01-15T09:30:00Z", "workflowName": "string", "contacts": [ { "id": 1, "name": "string", "title": "string", "description": "string", "emails": [ "string" ], "phones": [ "string" ], "isPrimary": true } ] } ] ``` **SDK Code** ```python import requests url = "https://api.coperniq.io/v1/projects" headers = {"x-api-key": ""} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.coperniq.io/v1/projects'; const options = {method: 'GET', headers: {'x-api-key': ''}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.coperniq.io/v1/projects" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("x-api-key", "") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.coperniq.io/v1/projects") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["x-api-key"] = '' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.coperniq.io/v1/projects") .header("x-api-key", "") .asString(); ``` ```php request('GET', 'https://api.coperniq.io/v1/projects', [ 'headers' => [ 'x-api-key' => '', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.coperniq.io/v1/projects"); var request = new RestRequest(Method.GET); request.AddHeader("x-api-key", ""); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["x-api-key": ""] let request = NSMutableURLRequest(url: NSURL(string: "https://api.coperniq.io/v1/projects")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```