# Projects

Manage and query projects in your organization.

Projects are the top-level containers for test runs, specs, and test results. Each project has a unique project ID and can be configured with various settings.

## List projects

> Get all projects for your organization with optional pagination

```json
{"openapi":"3.0.2","info":{"title":"Currents REST API","version":"1.0.0"},"tags":[{"name":"Projects","description":"Manage and query projects in your organization.\n\nProjects are the top-level containers for test runs, specs, and test results.\nEach project has a unique project ID and can be configured with various settings."}],"servers":[{"url":"https://api.currents.dev/v1","description":"Production API"},{"url":"https://api-staging.currents.dev/v1","description":"Staging API"},{"url":"http://localhost:4000/v1","description":"Local development"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key authentication using Bearer token"}},"parameters":{"LimitQuery":{"name":"limit","in":"query","required":false,"description":"Maximum number of items to return (default: 10)","schema":{"type":"integer","minimum":1,"maximum":100,"default":10}},"StartingAfterQuery":{"name":"starting_after","in":"query","required":false,"description":"Cursor for pagination. Returns items after this cursor value.","schema":{"type":"string"}},"EndingBeforeQuery":{"name":"ending_before","in":"query","required":false,"description":"Cursor for pagination. Returns items before this cursor value.","schema":{"type":"string"}}},"schemas":{"ProjectsListResponse":{"type":"object","required":["status","has_more","data"],"properties":{"status":{"type":"string","enum":["OK"]},"has_more":{"type":"boolean","description":"Whether there are more items to fetch"},"data":{"type":"array","items":{"$ref":"#/components/schemas/ProjectWithCursor"}}}},"ProjectWithCursor":{"allOf":[{"$ref":"#/components/schemas/Project"},{"type":"object","properties":{"cursor":{"type":"string","description":"Cursor for pagination"}}}]},"Project":{"type":"object","required":["projectId","name","createdAt"],"properties":{"projectId":{"type":"string","description":"Unique identifier for the project"},"name":{"type":"string","description":"Human-readable name for the project"},"createdAt":{"type":"string","format":"date-time","description":"When the project was created"},"failFast":{"type":"boolean","nullable":true,"description":"Whether fail-fast is enabled for this project"},"inactivityTimeoutSeconds":{"type":"integer","nullable":true,"description":"Timeout in seconds after which inactive runs are marked as timed out"},"defaultBranchName":{"type":"string","nullable":true,"description":"Default branch name for the project"}}},"ErrorResponse":{"type":"object","required":["status","error"],"properties":{"status":{"type":"string","enum":["FAILED"]},"error":{"type":"string","description":"Error message"}}}},"responses":{"BadRequest":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/projects":{"get":{"summary":"List projects","description":"Get all projects for your organization with optional pagination","operationId":"listProjects","tags":["Projects"],"parameters":[{"$ref":"#/components/parameters/LimitQuery"},{"$ref":"#/components/parameters/StartingAfterQuery"},{"$ref":"#/components/parameters/EndingBeforeQuery"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectsListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```

## Get project

> Get a single project by ID

```json
{"openapi":"3.0.2","info":{"title":"Currents REST API","version":"1.0.0"},"tags":[{"name":"Projects","description":"Manage and query projects in your organization.\n\nProjects are the top-level containers for test runs, specs, and test results.\nEach project has a unique project ID and can be configured with various settings."}],"servers":[{"url":"https://api.currents.dev/v1","description":"Production API"},{"url":"https://api-staging.currents.dev/v1","description":"Staging API"},{"url":"http://localhost:4000/v1","description":"Local development"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key authentication using Bearer token"}},"parameters":{"ProjectIdPath":{"name":"projectId","in":"path","required":true,"description":"The project ID","schema":{"type":"string"}}},"schemas":{"ProjectResponse":{"type":"object","required":["status","data"],"properties":{"status":{"type":"string","enum":["OK"]},"data":{"$ref":"#/components/schemas/Project"}}},"Project":{"type":"object","required":["projectId","name","createdAt"],"properties":{"projectId":{"type":"string","description":"Unique identifier for the project"},"name":{"type":"string","description":"Human-readable name for the project"},"createdAt":{"type":"string","format":"date-time","description":"When the project was created"},"failFast":{"type":"boolean","nullable":true,"description":"Whether fail-fast is enabled for this project"},"inactivityTimeoutSeconds":{"type":"integer","nullable":true,"description":"Timeout in seconds after which inactive runs are marked as timed out"},"defaultBranchName":{"type":"string","nullable":true,"description":"Default branch name for the project"}}},"ErrorResponse":{"type":"object","required":["status","error"],"properties":{"status":{"type":"string","enum":["FAILED"]},"error":{"type":"string","description":"Error message"}}}},"responses":{"BadRequest":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/projects/{projectId}":{"get":{"summary":"Get project","description":"Get a single project by ID","operationId":"getProject","tags":["Projects"],"parameters":[{"$ref":"#/components/parameters/ProjectIdPath"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## List project runs

> Get all runs for a project with optional pagination and filtering. Supports filtering by branch, tags, status, completion state, date range, search text, and author.

```json
{"openapi":"3.0.2","info":{"title":"Currents REST API","version":"1.0.0"},"tags":[{"name":"Projects","description":"Manage and query projects in your organization.\n\nProjects are the top-level containers for test runs, specs, and test results.\nEach project has a unique project ID and can be configured with various settings."},{"name":"Runs","description":"Query and manage test runs.\n\nA run represents a single execution of your test suite. Runs contain spec files\nwhich are executed across multiple instances. You can query run details, cancel\nruns, reset failed specs, and delete runs."}],"servers":[{"url":"https://api.currents.dev/v1","description":"Production API"},{"url":"https://api-staging.currents.dev/v1","description":"Staging API"},{"url":"http://localhost:4000/v1","description":"Local development"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key authentication using Bearer token"}},"parameters":{"ProjectIdPath":{"name":"projectId","in":"path","required":true,"description":"The project ID","schema":{"type":"string"}},"LimitQuery":{"name":"limit","in":"query","required":false,"description":"Maximum number of items to return (default: 10)","schema":{"type":"integer","minimum":1,"maximum":100,"default":10}},"StartingAfterQuery":{"name":"starting_after","in":"query","required":false,"description":"Cursor for pagination. Returns items after this cursor value.","schema":{"type":"string"}},"EndingBeforeQuery":{"name":"ending_before","in":"query","required":false,"description":"Cursor for pagination. Returns items before this cursor value.","schema":{"type":"string"}},"TagsQuery":{"name":"tags[]","in":"query","required":false,"description":"Filter by tags (can be specified multiple times using bracket notation, e.g., tags[]=value1&tags[]=value2)","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true},"BranchesQuery":{"name":"branches[]","in":"query","required":false,"description":"Filter by branches (can be specified multiple times using bracket notation, e.g., branches[]=main&branches[]=develop)","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true},"AuthorsQuery":{"name":"authors[]","in":"query","required":false,"description":"Filter by git authors (can be specified multiple times using bracket notation, e.g., authors[]=author1&authors[]=author2)","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true},"RunFeedBranchQuery":{"name":"branch","in":"query","required":false,"deprecated":true,"description":"Deprecated. Use branches[] instead. Filter runs by git branch name (single branch).","schema":{"type":"string"}},"RunFeedTagQuery":{"name":"tag","in":"query","required":false,"deprecated":true,"description":"Deprecated. Use tags[] instead. Filter runs by tags (can be specified multiple times). Use tag_operator to control matching behavior.","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true},"RunFeedTagOperatorQuery":{"name":"tag_operator","in":"query","required":false,"description":"Logical operator for tag filtering. AND requires all tags to be present (default), OR requires any tag to be present.","schema":{"type":"string","enum":["AND","OR"],"default":"AND"}},"RunFeedSearchQuery":{"name":"search","in":"query","required":false,"description":"Search runs by ciBuildId or commit message. Case-insensitive.","schema":{"type":"string","maxLength":200}},"RunFeedAuthorQuery":{"name":"author","in":"query","required":false,"deprecated":true,"description":"Deprecated. Use authors[] instead. Filter runs by git commit author name (can be specified multiple times).","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true},"RunFeedStatusQuery":{"name":"status","in":"query","required":false,"description":"Filter runs by status (can be specified multiple times). PASSED: all tests passed, FAILED: some tests failed, RUNNING: run is in progress and passing, FAILING: run is in progress but has failures.","schema":{"type":"array","items":{"type":"string","enum":["PASSED","FAILED","RUNNING","FAILING"]}},"style":"form","explode":true},"RunFeedCompletionStateQuery":{"name":"completion_state","in":"query","required":false,"description":"Filter runs by completion state (can be specified multiple times). COMPLETE: run finished normally, IN_PROGRESS: run is still executing, CANCELED: run was canceled, TIMEOUT: run timed out.","schema":{"type":"array","items":{"type":"string","enum":["COMPLETE","IN_PROGRESS","CANCELED","TIMEOUT"]}},"style":"form","explode":true},"RunFeedDateStartQuery":{"name":"date_start","in":"query","required":false,"description":"Filter runs created on or after this date (ISO 8601 format).","schema":{"type":"string","format":"date-time"}},"RunFeedDateEndQuery":{"name":"date_end","in":"query","required":false,"description":"Filter runs created before this date (ISO 8601 format).","schema":{"type":"string","format":"date-time"}}},"schemas":{"RunsListResponse":{"type":"object","required":["status","has_more","data"],"properties":{"status":{"type":"string","enum":["OK"]},"has_more":{"type":"boolean","description":"Whether there are more items to fetch"},"data":{"type":"array","items":{"$ref":"#/components/schemas/RunFeedItem"}}}},"RunFeedItem":{"allOf":[{"type":"object","properties":{"runId":{"type":"string"},"projectId":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"durationMs":{"type":"integer","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"previousRunId":{"type":"string","nullable":true},"cursor":{"type":"string"},"timeout":{"type":"object","properties":{"isTimeout":{"type":"boolean"},"timeoutValueMs":{"type":"integer","nullable":true}}},"cancellation":{"type":"object","nullable":true},"groups":{"type":"array","items":{"$ref":"#/components/schemas/RunGroup"}},"meta":{"$ref":"#/components/schemas/RunMeta"},"completionState":{"type":"string"},"status":{"type":"string"}}}]},"RunGroup":{"type":"object","properties":{"groupId":{"type":"string"},"platform":{"type":"object","properties":{"osName":{"type":"string"},"osVersion":{"type":"string"},"browserName":{"type":"string"},"browserVersion":{"type":"string"}}},"tests":{"type":"object","properties":{"overall":{"type":"integer"},"passes":{"type":"integer"},"failures":{"type":"integer"},"pending":{"type":"integer"},"skipped":{"type":"integer"},"flaky":{"type":"integer"}}}}},"RunMeta":{"type":"object","properties":{"ciBuildId":{"type":"string","description":"CI build identifier"},"commit":{"type":"object","properties":{"sha":{"type":"string"},"branch":{"type":"string"},"authorName":{"type":"string"},"authorEmail":{"type":"string"},"message":{"type":"string"},"remoteOrigin":{"type":"string"}}},"framework":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"}}}}},"ErrorResponse":{"type":"object","required":["status","error"],"properties":{"status":{"type":"string","enum":["FAILED"]},"error":{"type":"string","description":"Error message"}}}},"responses":{"BadRequest":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/projects/{projectId}/runs":{"get":{"summary":"List project runs","description":"Get all runs for a project with optional pagination and filtering. Supports filtering by branch, tags, status, completion state, date range, search text, and author.","operationId":"listProjectRuns","tags":["Projects","Runs"],"parameters":[{"$ref":"#/components/parameters/ProjectIdPath"},{"$ref":"#/components/parameters/LimitQuery"},{"$ref":"#/components/parameters/StartingAfterQuery"},{"$ref":"#/components/parameters/EndingBeforeQuery"},{"$ref":"#/components/parameters/TagsQuery"},{"$ref":"#/components/parameters/BranchesQuery"},{"$ref":"#/components/parameters/AuthorsQuery"},{"$ref":"#/components/parameters/RunFeedBranchQuery"},{"$ref":"#/components/parameters/RunFeedTagQuery"},{"$ref":"#/components/parameters/RunFeedTagOperatorQuery"},{"$ref":"#/components/parameters/RunFeedSearchQuery"},{"$ref":"#/components/parameters/RunFeedAuthorQuery"},{"$ref":"#/components/parameters/RunFeedStatusQuery"},{"$ref":"#/components/parameters/RunFeedCompletionStateQuery"},{"$ref":"#/components/parameters/RunFeedDateStartQuery"},{"$ref":"#/components/parameters/RunFeedDateEndQuery"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunsListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Get project insights

> Get aggregated run and test metrics for a project within a date range

```json
{"openapi":"3.0.2","info":{"title":"Currents REST API","version":"1.0.0"},"tags":[{"name":"Projects","description":"Manage and query projects in your organization.\n\nProjects are the top-level containers for test runs, specs, and test results.\nEach project has a unique project ID and can be configured with various settings."}],"servers":[{"url":"https://api.currents.dev/v1","description":"Production API"},{"url":"https://api-staging.currents.dev/v1","description":"Staging API"},{"url":"http://localhost:4000/v1","description":"Local development"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key authentication using Bearer token"}},"parameters":{"ProjectIdPath":{"name":"projectId","in":"path","required":true,"description":"The project ID","schema":{"type":"string"}},"DateStartQuery":{"name":"date_start","in":"query","required":true,"description":"Start date in ISO 8601 format","schema":{"type":"string","format":"date-time"}},"DateEndQuery":{"name":"date_end","in":"query","required":true,"description":"End date in ISO 8601 format","schema":{"type":"string","format":"date-time"}},"ResolutionQuery":{"name":"resolution","in":"query","required":false,"description":"Time resolution for histogram data","schema":{"type":"string","enum":["1h","1d","1w"],"default":"1d"}},"TagsQuery":{"name":"tags[]","in":"query","required":false,"description":"Filter by tags (can be specified multiple times using bracket notation, e.g., tags[]=value1&tags[]=value2)","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true},"BranchesQuery":{"name":"branches[]","in":"query","required":false,"description":"Filter by branches (can be specified multiple times using bracket notation, e.g., branches[]=main&branches[]=develop)","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true},"GroupsQuery":{"name":"groups[]","in":"query","required":false,"description":"Filter by groups (can be specified multiple times using bracket notation, e.g., groups[]=group1&groups[]=group2)","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true},"AuthorsQuery":{"name":"authors[]","in":"query","required":false,"description":"Filter by git authors (can be specified multiple times using bracket notation, e.g., authors[]=author1&authors[]=author2)","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true}},"schemas":{"ProjectInsightsResponse":{"type":"object","required":["status","data"],"properties":{"status":{"type":"string","enum":["OK"]},"data":{"type":"object","properties":{"projectId":{"type":"string"},"orgId":{"type":"string"},"dateStart":{"type":"string","format":"date-time"},"dateEnd":{"type":"string","format":"date-time"},"resolution":{"type":"string"},"results":{"type":"object","properties":{"overall":{"type":"object","properties":{"runs":{"$ref":"#/components/schemas/RunMetrics"},"tests":{"$ref":"#/components/schemas/TestMetrics"}}},"timeline":{"type":"array","items":{"type":"object","additionalProperties":{"type":"object","properties":{"runs":{"$ref":"#/components/schemas/RunMetrics"},"tests":{"$ref":"#/components/schemas/TestMetrics"}}}}}}}}}}},"RunMetrics":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of runs"},"cancelled":{"type":"integer","description":"Cancelled runs"},"timeouts":{"type":"integer","description":"Timed out runs"},"completed":{"type":"integer","description":"Fully completed runs"},"failed":{"type":"integer","description":"Failed runs"},"passed":{"type":"integer","description":"Passed runs"},"nonFullyReported":{"type":"integer","description":"Runs that did not fully report"},"avgDurationSeconds":{"type":"number","description":"Average run duration in seconds"},"avgSuccessRate":{"type":"number","description":"Average success rate (0-1)"}}},"TestMetrics":{"type":"object","properties":{"total":{"type":"integer","description":"Total test executions"},"failed":{"type":"integer","description":"Failed tests"},"passed":{"type":"integer","description":"Passed tests"},"pending":{"type":"integer","description":"Pending tests"},"skipped":{"type":"integer","description":"Skipped tests"},"flaky":{"type":"integer","description":"Flaky tests"}}},"ErrorResponse":{"type":"object","required":["status","error"],"properties":{"status":{"type":"string","enum":["FAILED"]},"error":{"type":"string","description":"Error message"}}}},"responses":{"BadRequest":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/projects/{projectId}/insights":{"get":{"summary":"Get project insights","description":"Get aggregated run and test metrics for a project within a date range","operationId":"getProjectInsights","tags":["Projects"],"parameters":[{"$ref":"#/components/parameters/ProjectIdPath"},{"$ref":"#/components/parameters/DateStartQuery"},{"$ref":"#/components/parameters/DateEndQuery"},{"$ref":"#/components/parameters/ResolutionQuery"},{"$ref":"#/components/parameters/TagsQuery"},{"$ref":"#/components/parameters/BranchesQuery"},{"$ref":"#/components/parameters/GroupsQuery"},{"$ref":"#/components/parameters/AuthorsQuery"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectInsightsResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```