> For the complete documentation index, see [llms.txt](https://docs.currents.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.currents.dev/api/resources/integrations.md).

# Integrations

Manage third-party integrations such as Jira.

## Create Jira issue from a run test

> Creates a Jira issue using the organization Jira integration, with title and description built from the specified run and test (same linking behavior as the dashboard). Identifies the Jira site via \`jiraInstallationId\` (shown in the dashboard as Installation ID). Requires a write-scoped API key. On 404, the \`error\` field indicates whether the Currents project, Jira installation, run, or test was not found.

```json
{"openapi":"3.0.2","info":{"title":"Currents REST API","version":"1.0.0"},"tags":[{"name":"Integrations","description":"Manage third-party integrations such as Jira."}],"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":{"CreateJiraIssueFromRunTestRequest":{"type":"object","required":["runId","testId","jiraInstallationId","jiraProjectId","jiraIssueType"],"properties":{"runId":{"type":"string","minLength":1,"description":"Currents run ID containing the test"},"testId":{"type":"string","minLength":1,"description":"Test ID within the run (client test id)"},"jiraInstallationId":{"type":"string","minLength":1,"description":"Atlassian Jira installation ID for the org integration (same as Installation ID in the dashboard)"},"jiraProjectId":{"type":"string","minLength":1,"description":"Jira project ID in which to create the issue"},"jiraIssueType":{"type":"string","minLength":1,"description":"Jira issue type ID"},"customFields":{"type":"array","items":{"type":"object","required":["fieldId","value"],"properties":{"fieldId":{"type":"string","minLength":1,"description":"Jira field ID (matches `fieldId` from issue type discovery)"},"value":{"type":"string","minLength":1,"description":"String representation for the field value (encoding depends on field type; see Jira custom field docs)"}}},"description":"Optional Jira custom fields"}}},"CreateJiraIssueFromRunTestResponse":{"type":"object","required":["status","data"],"properties":{"status":{"type":"string","enum":["OK"]},"data":{"$ref":"#/components/schemas/JiraIssueFromRunTestResult"}}},"JiraIssueFromRunTestResult":{"type":"object","required":["jiraIssueKey","currentsIssueId","jiraIssueUrl","currentsIssueUrl"],"properties":{"jiraIssueKey":{"type":"string","description":"Jira issue key (e.g. PROJ-123)"},"currentsIssueId":{"type":"string","description":"Currents issue record ID"},"jiraIssueUrl":{"type":"string","nullable":true,"description":"URL to the Jira issue in the linked Jira instance"},"currentsIssueUrl":{"type":"string","description":"URL to the Currents dashboard issue modal for the linked test entity"}}},"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"}}}},"Forbidden":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Conflict":{"description":"Request could not be completed due to a conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"TooManyRequests":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/projects/{projectId}/jira/issues":{"post":{"summary":"Create Jira issue from a run test","description":"Creates a Jira issue using the organization Jira integration, with title and description built from the specified run and test (same linking behavior as the dashboard). Identifies the Jira site via `jiraInstallationId` (shown in the dashboard as Installation ID). Requires a write-scoped API key. On 404, the `error` field indicates whether the Currents project, Jira installation, run, or test was not found.","operationId":"createJiraIssueFromRunTest","tags":["Integrations"],"parameters":[{"$ref":"#/components/parameters/ProjectIdPath"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateJiraIssueFromRunTestRequest"}}}},"responses":{"201":{"description":"Jira issue created and linked to the test","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateJiraIssueFromRunTestResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Link existing Jira issue to a run test

> Creates a link between an existing Jira issue (identified by \`jiraIssueKey\` in the path, e.g. PROJ-123) and the specified run and test. Same behavior as the dashboard link flow: resolves the test entity, builds the Currents issue title and Jira comment from the test (optionally prefixed with your \`comment\`), posts the comment on the Jira issue, and attaches the Jira ticket to the Currents issue. Identifies the Jira site via \`jiraInstallationId\` (Installation ID in the dashboard). \`jiraIssueType\` is stored on the ticket metadata (use the same value as when creating issues via the REST API, typically the issue type ID from issue type discovery). Requires a write-scoped API key. On 404, the \`error\` field indicates whether the Currents project, Jira installation, run, or test was not found.

```json
{"openapi":"3.0.2","info":{"title":"Currents REST API","version":"1.0.0"},"tags":[{"name":"Integrations","description":"Manage third-party integrations such as Jira."}],"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"}},"JiraIssueKeyPath":{"name":"jiraIssueKey","in":"path","required":true,"description":"Jira issue key to link (e.g. PROJ-123), as shown in Jira. Must be 1–255 characters after trimming. If missing, empty, or longer than 255 characters, the server responds with HTTP 400 and an `ErrorResponse`.","schema":{"type":"string","minLength":1,"maxLength":255}}},"schemas":{"LinkJiraIssueFromRunTestRequest":{"type":"object","required":["runId","testId","jiraInstallationId","jiraProjectId","jiraIssueType"],"properties":{"runId":{"type":"string","minLength":1,"description":"Currents run ID containing the test"},"testId":{"type":"string","minLength":1,"description":"Test ID within the run (client test id)"},"jiraInstallationId":{"type":"string","minLength":1,"description":"Atlassian Jira installation ID for the org integration (same as Installation ID in the dashboard)"},"jiraProjectId":{"type":"string","minLength":1,"description":"Jira project ID for the linked issue"},"jiraIssueType":{"type":"string","minLength":1,"description":"Jira issue type identifier stored on the Currents ticket (same as `jiraIssueType` when creating issues; use issue type discovery when unsure)"},"comment":{"type":"string","description":"Optional text prepended to the Jira comment and Currents issue description before the automated test context (when `includeContextInComment` is true)"},"includeContextInComment":{"type":"boolean","default":true,"description":"When true (default), appends the same automated test context used when creating Jira issues from a run test. When false, `comment` must be non-empty and is used alone for the Jira comment and issue description."}},"allOf":[{"if":{"properties":{"includeContextInComment":{"const":false}},"required":["includeContextInComment"]},"then":{"required":["comment"],"properties":{"comment":{"type":"string","minLength":1,"description":"Required when `includeContextInComment` is false; used alone for the Jira comment and issue description"}}}}]},"LinkJiraIssueFromRunTestResponse":{"type":"object","required":["status","data"],"properties":{"status":{"type":"string","enum":["OK"]},"data":{"$ref":"#/components/schemas/JiraIssueFromRunTestResult"}}},"JiraIssueFromRunTestResult":{"type":"object","required":["jiraIssueKey","currentsIssueId","jiraIssueUrl","currentsIssueUrl"],"properties":{"jiraIssueKey":{"type":"string","description":"Jira issue key (e.g. PROJ-123)"},"currentsIssueId":{"type":"string","description":"Currents issue record ID"},"jiraIssueUrl":{"type":"string","nullable":true,"description":"URL to the Jira issue in the linked Jira instance"},"currentsIssueUrl":{"type":"string","description":"URL to the Currents dashboard issue modal for the linked test entity"}}},"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"}}}},"Forbidden":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Conflict":{"description":"Request could not be completed due to a conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"TooManyRequests":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/projects/{projectId}/jira/issues/{jiraIssueKey}/link":{"post":{"summary":"Link existing Jira issue to a run test","description":"Creates a link between an existing Jira issue (identified by `jiraIssueKey` in the path, e.g. PROJ-123) and the specified run and test. Same behavior as the dashboard link flow: resolves the test entity, builds the Currents issue title and Jira comment from the test (optionally prefixed with your `comment`), posts the comment on the Jira issue, and attaches the Jira ticket to the Currents issue. Identifies the Jira site via `jiraInstallationId` (Installation ID in the dashboard). `jiraIssueType` is stored on the ticket metadata (use the same value as when creating issues via the REST API, typically the issue type ID from issue type discovery). Requires a write-scoped API key. On 404, the `error` field indicates whether the Currents project, Jira installation, run, or test was not found.","operationId":"linkJiraIssueFromRunTest","tags":["Integrations"],"parameters":[{"$ref":"#/components/parameters/ProjectIdPath"},{"$ref":"#/components/parameters/JiraIssueKeyPath"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkJiraIssueFromRunTestRequest"}}}},"responses":{"200":{"description":"Jira issue linked to the test","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkJiraIssueFromRunTestResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## List Jira projects

> Lists Jira projects available for the organization Jira integration (via Atlassian project search). Use returned project IDs as \`jiraProjectId\` when creating or linking Jira issues.

```json
{"openapi":"3.0.2","info":{"title":"Currents REST API","version":"1.0.0"},"tags":[{"name":"Integrations","description":"Manage third-party integrations such as Jira."}],"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":{"JiraInstallationIdQuery":{"name":"jira_installation_id","in":"query","required":true,"description":"Atlassian Jira installation ID for the org integration (same as Installation ID in the dashboard)","schema":{"type":"string","minLength":1}},"JiraDiscoverySearchQuery":{"name":"search","in":"query","required":false,"description":"Case-insensitive search filter for Jira metadata","schema":{"type":"string"}},"PageQuery":{"name":"page","in":"query","required":false,"description":"Page number (0-indexed)","schema":{"type":"integer","minimum":0,"default":0}},"JiraDiscoveryLimitQuery":{"name":"limit","in":"query","required":false,"description":"Page size for Jira discovery list endpoints (default 50, max 100)","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}},"schemas":{"JiraProjectsDiscoveryResponse":{"type":"object","required":["status","data"],"properties":{"status":{"type":"string","enum":["OK"]},"data":{"type":"object","required":["list","count","total","nextPage"],"properties":{"list":{"type":"array","items":{"$ref":"#/components/schemas/JiraProjectDiscovery"}},"count":{"type":"integer","description":"Number of items in the current response"},"total":{"type":"integer","description":"Total number of matching Jira projects"},"nextPage":{"oneOf":[{"type":"integer"},{"type":"boolean","enum":[false]}],"description":"Next page index (0-based), or false if there is no next page"}}}}},"JiraProjectDiscovery":{"type":"object","required":["id","key","name","description","avatarUrl"],"properties":{"id":{"type":"string","description":"Jira project ID used as jiraProjectId in create-issue body"},"key":{"type":"string","description":"Jira project key"},"name":{"type":"string","description":"Jira project name"},"description":{"type":"string","nullable":true,"description":"Jira project description"},"avatarUrl":{"type":"string","nullable":true,"description":"Jira project avatar URL"}}},"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"}}}},"Conflict":{"description":"Request could not be completed due to a conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"TooManyRequests":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/integrations/jira/projects":{"get":{"summary":"List Jira projects","description":"Lists Jira projects available for the organization Jira integration (via Atlassian project search). Use returned project IDs as `jiraProjectId` when creating or linking Jira issues.","operationId":"listJiraProjects","tags":["Integrations"],"parameters":[{"$ref":"#/components/parameters/JiraInstallationIdQuery"},{"$ref":"#/components/parameters/JiraDiscoverySearchQuery"},{"$ref":"#/components/parameters/PageQuery"},{"$ref":"#/components/parameters/JiraDiscoveryLimitQuery"}],"responses":{"200":{"description":"Jira projects returned successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JiraProjectsDiscoveryResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## List Jira issue types

> Lists Jira issue types available for a Jira project and embeds custom fields required to create issues through the REST API.

```json
{"openapi":"3.0.2","info":{"title":"Currents REST API","version":"1.0.0"},"tags":[{"name":"Integrations","description":"Manage third-party integrations such as Jira."}],"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":{"JiraProjectIdPath":{"name":"jiraProjectId","in":"path","required":true,"description":"Jira project ID (from project search or Jira). Must be 1–128 characters. If missing, empty, or longer than 128 characters, the server responds with HTTP 400 and an `ErrorResponse` (`status: FAILED`, `error` describing the validation failure).","schema":{"type":"string","minLength":1,"maxLength":128}},"JiraInstallationIdQuery":{"name":"jira_installation_id","in":"query","required":true,"description":"Atlassian Jira installation ID for the org integration (same as Installation ID in the dashboard)","schema":{"type":"string","minLength":1}},"JiraDiscoverySearchQuery":{"name":"search","in":"query","required":false,"description":"Case-insensitive search filter for Jira metadata","schema":{"type":"string"}},"PageQuery":{"name":"page","in":"query","required":false,"description":"Page number (0-indexed)","schema":{"type":"integer","minimum":0,"default":0}},"JiraDiscoveryLimitQuery":{"name":"limit","in":"query","required":false,"description":"Page size for Jira discovery list endpoints (default 50, max 100)","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}},"schemas":{"JiraIssueTypesDiscoveryResponse":{"type":"object","required":["status","data"],"properties":{"status":{"type":"string","enum":["OK"]},"data":{"type":"object","required":["list","count","total","nextPage"],"properties":{"list":{"type":"array","items":{"$ref":"#/components/schemas/JiraIssueTypeDiscovery"}},"count":{"type":"integer","description":"Number of items in the current response"},"total":{"type":"integer","description":"Total number of matching Jira issue types"},"nextPage":{"oneOf":[{"type":"integer"},{"type":"boolean","enum":[false]}],"description":"Next page index (0-based), or false if there is no next page"}}}}},"JiraIssueTypeDiscovery":{"type":"object","required":["id","name","description","iconUrl","projectId","customFields"],"properties":{"id":{"type":"string","description":"Jira issue type ID used as jiraIssueType in create-issue body"},"name":{"type":"string","description":"Jira issue type name"},"description":{"type":"string","nullable":true,"description":"Jira issue type description"},"iconUrl":{"type":"string","nullable":true,"description":"Jira issue type icon URL"},"projectId":{"type":"string","nullable":true,"description":"Jira project ID for project-scoped issue types, or null for global issue types"},"customFields":{"type":"array","items":{"$ref":"#/components/schemas/JiraCustomFieldDiscovery"}}}},"JiraCustomFieldDiscovery":{"type":"object","required":["fieldId","key","name","required","fieldType","allowedValues","originalType"],"properties":{"fieldId":{"type":"string","description":"Jira field ID to use in customFields.fieldId"},"key":{"type":"string"},"name":{"type":"string"},"required":{"type":"boolean"},"fieldType":{"$ref":"#/components/schemas/JiraFieldType"},"allowedValues":{"type":"array","items":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}}},"originalType":{"type":"string","nullable":true,"description":"Original Jira schema type"}}},"JiraFieldType":{"type":"string","enum":["TEXT","SELECT","MULTI_SELECT","CHECKBOX","LABELS","NUMBER","DATE","DATETIME","USER","MULTI_USER","UNSUPPORTED"]},"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"}}}},"Conflict":{"description":"Request could not be completed due to a conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"TooManyRequests":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/integrations/jira/projects/{jiraProjectId}/issue-types":{"get":{"summary":"List Jira issue types","description":"Lists Jira issue types available for a Jira project and embeds custom fields required to create issues through the REST API.","operationId":"listJiraIssueTypes","tags":["Integrations"],"parameters":[{"$ref":"#/components/parameters/JiraProjectIdPath"},{"$ref":"#/components/parameters/JiraInstallationIdQuery"},{"$ref":"#/components/parameters/JiraDiscoverySearchQuery"},{"$ref":"#/components/parameters/PageQuery"},{"$ref":"#/components/parameters/JiraDiscoveryLimitQuery"}],"responses":{"200":{"description":"Jira issue types returned successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JiraIssueTypesDiscoveryResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.currents.dev/api/resources/integrations.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.