Introduction
# Jira
Access the Jira Cloud API with managed OAuth authentication. Search issues with JQL, create and manage issues, and automate workflows.
## Quick Start
```bash # First, get your cloud ID python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/jira/oauth/token/accessible-resources') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF
# Then search issues python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/jira/ex/jira/{cloudId}/rest/api/3/search/jql?jql=project%3DKEY&maxResults=10') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
## Base URL
``` https://gateway.maton.ai/jira/{native-api-path} ```
Replace `{native-api-path}` with the actual Jira API endpoint path. The gateway proxies requests to `api.atlassian.com` and automatically injects your OAuth token.
## Getting Cloud ID
Jira Cloud requires a cloud ID. Get it first:
```bash GET /jira/oauth/token/accessible-resources ```
Response:
```json [{ "id": "62909843-b784-4c35-b770-e4e2a26f024b", "url": "https://yoursite.atlassian.net", "name": "yoursite" }] ```
## Authentication
All requests require the Maton API key in the Authorization header:
``` Authorization: Bearer $MATON_API_KEY ```
**Environment Variable:** Set your API key as `MATON_API_KEY`:
```bash export MATON_API_KEY="YOUR_API_KEY" ```
### Getting Your API Key
1. Sign in or create an account at [maton.ai](https://maton.ai) 2. Go to [maton.ai/settings](https://maton.ai/settings) 3. Copy your API key
## Connection Management
Manage your Jira OAuth connections at `https://ctrl.maton.ai`.
### List Connections
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=jira&status=ACTIVE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### Create Connection
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'jira'}).encode() req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### Get Connection
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**Response:** ```json { "connection": { "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80", "status": "ACTIVE", "creation_time": "2025-12-08T07:20:53.488460Z", "last_updated_time": "2026-01-31T20:03:32.593153Z", "url": "https://connect.maton.ai/?session_token=...", "app": "jira", "metadata": {} } } ```
Open the returned `url` in a browser to complete OAuth authorization.
### Delete Connection
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### Specifying Connection
If you have multiple Jira connections, specify which one to use with the `Maton-Connection` header:
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/jira/ex/jira/{cloudId}/rest/api/3/project') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
If omitted, the gateway uses the default (oldest) active connection.
## API Reference
### Projects
#### List Projects
```bash GET /jira/ex/jira/{cloudId}/rest/api/3/project ```
#### Get Project
```bash GET /jira/ex/jira/{cloudId}/rest/api/3/project/{projectKeyOrId} ```
### Issues
#### Search Issues (JQL)
```bash GET /jira/ex/jira/{cloudId}/rest/api/3/search/jql?jql=project%3DKEY%20order%20by%20created%20DESC&maxResults=20&fields=summary,status,assignee ```
#### Get Issue
```bash GET /jira/ex/jira/{cloudId}/rest/api/3/issue/{issueIdOrKey} ```
#### Create Issue
```bash POST /jira/ex/jira/{cloudId}/rest/api/3/issue Content-Type: application/json
{ "fields": { "project": {"key": "PROJ"}, "summary": "Issue summary", "issuetype": {"name": "Task"} } } ```
#### Update Issue
```bash PUT /jira/ex/jira/{cloudId}/rest/api/3/issue/{issueIdOrKey} Content-Type: application/json
{ "fields": { "summary": "Updated summary" } } ```
#### Delete Issue
```bash DELETE /jira/ex/jira/{cloudId}/rest/api/3/issue/{issueIdOrKey} ```
#### Assign Issue
```bash PUT /jira/ex/jira/{cloudId}/rest/api/3/issue/{issueIdOrKey}/assignee Content-Type: application/json
{ "accountId": "712020:5aff718e-6fe0-4548-82f4-f44ec481e5e7" } ```
### Transitions
#### Get Transitions
```bash GET /jira/ex/jira/{cloudId}/rest/api/3/issue/{issueIdOrKey}/transitions ```
#### Transition Issue (change status)
```bash POST /jira/ex/jira/{cloudId}/rest/api/3/issue/{issueIdOrKey}/transitions Content-Type: application/json
{ "transition": {"id": "31"} } ```
### Comments
#### Get Comments
```bash GET /jira/ex/jira/{cloudId}/rest/api/3/issue/{issueIdOrKey}/comment ```
#### Add Comment
```bash POST /jira/ex/jira/{cloudId}/rest/api/3/issue/{issueIdOrKey}/comment Content-Type: application/json
{ "body": { "type": "doc", "version": 1, "content": [{"type": "paragraph", "content": [{"type": "text", "text": "Comment text"}]}] } } ```
### Users
#### Get Current User
```bash GET /jira/ex/jira/{cloudId}/rest/api/3/myself ```
#### Search Users
```bash GET /jira/ex/jira/{cloudId}/rest/api/3/user/search?query=john ```
### Metadata
#### List Issue Types
```bash GET /jira/ex/jira/{cloudId}/rest/api/3/issuetype ```
#### List Priorities
```bash GET /jira/ex/jira/{cloudId}/rest/api/3/priority ```
#### List Statuses
```bash GET /jira/ex/jira/{cloudId}/rest/api/3/status ```
## Code Examples
### JavaScript
```javascript // Get cloud ID first const resources = await fetch( 'https://gateway.maton.ai/jira/oauth/token/accessible-resources', { headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}` } } ).then(r => r.json());
const cloudId = resources[0].id;
// Search issues const issues = await fetch( `https://gateway.maton.ai/jira/ex/jira/${cloudId}/rest/api/3/search/jql?jql=project=KEY`, { headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}` } } ).then(r => r.json()); ```
### Python
```python import os import requests
headers = {'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}
# Get cloud ID resources = requests.get( 'https://gateway.maton.ai/jira/oauth/token/accessible-resources', headers=headers ).json()
cloud_id = resources[0]['id']
# Search issues issues = requests.get( f'https://gateway.maton.ai/jira/ex/jira/{cloud_id}/rest/api/3/search/jql', headers=headers, params={'jql': 'project=KEY', 'maxResults': 10} ).json() ```
## Notes
- Always fetch cloud ID first using `/oauth/token/accessible-resources` - JQL queries must be bounded (e.g., `project=KEY`) - Use URL encoding for JQL query parameters - Update, Delete, Transition return HTTP 204 on success - Agile API requires additional OAuth scopes. If you receive a scope error, contact Maton support at [email protected] with the specific operations/APIs you need and your use-case - IMPORTANT: When using curl commands, use `curl -g` when URLs contain brackets (`fields[]`, `sort[]`, `records[]`) to disable glob parsing - IMPORTANT: When piping curl output to `jq` or other commands, environment variables like `$MATON_API_KEY` may not expand correctly in some shell environments. You may get "Invalid API key" errors when piping.
## Error Handling
| Status | Meaning | |--------|---------| | 400 | Missing Jira connection or invalid JQL | | 401 | Invalid or missing Maton API key | | 429 | Rate limited (10 req/sec per account) | | 4xx/5xx | Passthrough error from Jira API |
### Troubleshooting: API Key Issues
1. Check that the `MATON_API_KEY` environment variable is set:
```bash echo $MATON_API_KEY ```
2. Verify the API key is valid by listing connections:
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### Troubleshooting: Invalid App Name
1. Ensure your URL path starts with `jira`. For example:
- Correct: `https://gateway.maton.ai/jira/ex/jira/{cloudId}/rest/api/3/project` - Incorrect: `https://gateway.maton.ai/ex/jira/{cloudId}/rest/api/3/project`
## Resources
- [Jira API Introduction](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/) - [Search Issues (JQL)](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-search/#api-rest-api-3-search-jql-get) - [Get Issue](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-issueidorkey-get) - [Create Issue](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-post) - [Transition Issue](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-issueidorkey-transitions-post) - [JQL Reference](https://support.atlassian.com/jira-service-management-cloud/docs/use-advanced-search-with-jira-query-language-jql/) - [Maton Community](https://discord.com/invite/dBfFAcefs2) - [Maton Support](mailto:[email protected])