\r \r

Jules API Skill\r

\r Interact with the Google Jules AI coding agent via its REST API. Jules can autonomously execute coding tasks on your GitHub repositories — writing code, fixing bugs, adding tests, and creating pull requests.\r \r Base URL: https://jules.googleapis.com/v1alpha\r Auth: Pass your API key via the x-goog-api-key header. Get one at jules.google.com/settings.\r \r ---\r \r

List Sources (Connected Repositories)\r

\r Discover which GitHub repos are connected to your Jules account:\r \r

curl -s -H "x-goog-api-key: $JULES_API_KEY" \\r
  "https://jules.googleapis.com/v1alpha/sources?pageSize=30"\r
```\r
\r
With pagination:\r
\r
```bash\r
curl -s -H "x-goog-api-key: $JULES_API_KEY" \\r
  "https://jules.googleapis.com/v1alpha/sources?pageSize=10&pageToken=PAGE_TOKEN"\r
```\r
\r
Filter specific sources:\r
\r
```bash\r
curl -s -H "x-goog-api-key: $JULES_API_KEY" \\r
  "https://jules.googleapis.com/v1alpha/sources?filter=name%3Dsources%2Fgithub-owner-repo"\r
```\r
\r
## Get a Source\r
\r
Get details and branches for a specific repo:\r
\r
```bash\r
curl -s -H "x-goog-api-key: $JULES_API_KEY" \\r
  "https://jules.googleapis.com/v1alpha/sources/SOURCE_ID"\r
```\r
\r
Example: `sources/github-myorg-myrepo` — replace with your actual source ID from List Sources.\r
\r
---\r
\r
## Create a Session (Start a Coding Task)\r
\r
Create a new Jules session to execute a coding task on a repo:\r
\r
```bash\r
curl -s -X POST \\r
  -H "x-goog-api-key: $JULES_API_KEY" \\r
  -H "Content-Type: application/json" \\r
  -d '{\r
    "prompt": "TASK_DESCRIPTION",\r
    "title": "OPTIONAL_TITLE",\r
    "sourceContext": {\r
      "source": "sources/github-OWNER-REPO",\r
      "githubRepoContext": {\r
        "startingBranch": "main"\r
      }\r
    },\r
    "requirePlanApproval": true\r
  }' \\r
  "https://jules.googleapis.com/v1alpha/sessions"\r
```\r
\r
### Parameters\r
\r
| Parameter | Required | Description |\r
|---|---|---|\r
| `prompt` | Yes | The task description for Jules to execute |\r
| `title` | No | Optional title (auto-generated if omitted) |\r
| `sourceContext.source` | Yes | Source resource name (e.g. `sources/github-owner-repo`) |\r
| `sourceContext.githubRepoContext.startingBranch` | Yes | Branch to start from (e.g. `main`, `develop`) |\r
| `requirePlanApproval` | No | If `true`, plans need explicit approval before execution |\r
| `automationMode` | No | Set to `AUTO_CREATE_PR` to auto-create PRs when done |\r
\r
### Auto-approve + Auto-PR example\r
\r
```bash\r
curl -s -X POST \\r
  -H "x-goog-api-key: $JULES_API_KEY" \\r
  -H "Content-Type: application/json" \\r
  -d '{\r
    "prompt": "Add comprehensive unit tests for the auth module",\r
    "sourceContext": {\r
      "source": "sources/github-myorg-myrepo",\r
      "githubRepoContext": { "startingBranch": "main" }\r
    },\r
    "automationMode": "AUTO_CREATE_PR"\r
  }' \\r
  "https://jules.googleapis.com/v1alpha/sessions"\r
```\r
\r
---\r
\r
## List Sessions\r
\r
List all your Jules sessions:\r
\r
```bash\r
curl -s -H "x-goog-api-key: $JULES_API_KEY" \\r
  "https://jules.googleapis.com/v1alpha/sessions?pageSize=10"\r
```\r
\r
Paginate with `pageToken`:\r
\r
```bash\r
curl -s -H "x-goog-api-key: $JULES_API_KEY" \\r
  "https://jules.googleapis.com/v1alpha/sessions?pageSize=10&pageToken=NEXT_PAGE_TOKEN"\r
```\r
\r
## Get a Session\r
\r
Retrieve a single session by ID (includes outputs like PRs if completed):\r
\r
```bash\r
curl -s -H "x-goog-api-key: $JULES_API_KEY" \\r
  "https://jules.googleapis.com/v1alpha/sessions/SESSION_ID"\r
```\r
\r
### Session States\r
\r
| State | Meaning |\r
|---|---|\r
| `QUEUED` | Waiting to be processed |\r
| `PLANNING` | Jules is analyzing and creating a plan |\r
| `AWAITING_PLAN_APPROVAL` | Plan ready, waiting for user approval |\r
| `AWAITING_USER_FEEDBACK` | Jules needs additional input |\r
| `IN_PROGRESS` | Jules is actively working |\r
| `PAUSED` | Session is paused |\r
| `COMPLETED` | Task completed successfully |\r
| `FAILED` | Task failed to complete |\r
\r
---\r
\r
## Approve a Plan\r
\r
When a session is in `AWAITING_PLAN_APPROVAL` state, approve the plan:\r
\r
```bash\r
curl -s -X POST \\r
  -H "x-goog-api-key: $JULES_API_KEY" \\r
  -H "Content-Type: application/json" \\r
  -d '{}' \\r
  "https://jules.googleapis.com/v1alpha/sessions/SESSION_ID:approvePlan"\r
```\r
\r
## Send a Message\r
\r
Send feedback, answer questions, or give additional instructions to an active session:\r
\r
```bash\r
curl -s -X POST \\r
  -H "x-goog-api-key: $JULES_API_KEY" \\r
  -H "Content-Type: application/json" \\r
  -d '{\r
    "prompt": "YOUR_MESSAGE_HERE"\r
  }' \\r
  "https://jules.googleapis.com/v1alpha/sessions/SESSION_ID:sendMessage"\r
```\r
\r
Use this when session state is `AWAITING_USER_FEEDBACK` or to provide additional guidance during `IN_PROGRESS`.\r
\r
---\r
\r
## List Activities (Monitor Progress)\r
\r
Get all events/progress for a session:\r
\r
```bash\r
curl -s -H "x-goog-api-key: $JULES_API_KEY" \\r
  "https://jules.googleapis.com/v1alpha/sessions/SESSION_ID/activities?pageSize=50"\r
```\r
\r
Get activities after a specific timestamp (for polling):\r
\r
```bash\r
curl -s -H "x-goog-api-key: $JULES_API_KEY" \\r
  "https://jules.googleapis.com/v1alpha/sessions/SESSION_ID/activities?createTime=2026-01-17T00:03:53Z"\r
```\r
\r
### Activity Types\r
\r
Activities will contain exactly one of these event fields:\r
\r
| Event | Description |\r
|---|---|\r
| `planGenerated` | Jules created a plan (contains `plan.steps[]`) |\r
| `planApproved` | A plan was approved |\r
| `userMessaged` | User sent a message |\r
| `agentMessaged` | Jules sent a message |\r
| `progressUpdated` | Status update during execution |\r
| `sessionCompleted` | Session finished successfully |\r
| `sessionFailed` | Session encountered an error (contains `reason`) |\r
\r
### Artifacts\r
\r
Activities may include artifacts:\r
\r
- **ChangeSet**: Code changes with `gitPatch` (unified diff, base commit, suggested commit message)\r
- **BashOutput**: Command output with `command`, `output`, `exitCode`\r
- **Media**: Binary output with `mimeType` and base64 `data`\r
\r
## Get a Single Activity\r
\r
```bash\r
curl -s -H "x-goog-api-key: $JULES_API_KEY" \\r
  "https://jules.googleapis.com/v1alpha/sessions/SESSION_ID/activities/ACTIVITY_ID"\r
```\r
\r
---\r
\r
## Delete a Session\r
\r
```bash\r
curl -s -X DELETE \\r
  -H "x-goog-api-key: $JULES_API_KEY" \\r
  "https://jules.googleapis.com/v1alpha/sessions/SESSION_ID"\r
```\r
\r
---\r
\r
## Typical Workflow\r
\r
1. **List sources** to find the repo resource name\r
2. **Create a session** with a prompt describing the task\r
3. **Poll the session** (Get Session) to track state changes\r
4. **List activities** to monitor progress and read Jules' messages\r
5. If `requirePlanApproval` was set, **approve the plan** when state is `AWAITING_PLAN_APPROVAL`\r
6. If state is `AWAITING_USER_FEEDBACK`, **send a message** with your response\r
7. When `COMPLETED`, **get the session** to find the output PR URL\r
\r
## Error Handling\r
\r
| Code | Meaning |\r
|---|---|\r
| 200 | Success |\r
| 400 | Bad request (invalid parameters) |\r
| 401 | Unauthorized (invalid/missing API key) |\r
| 403 | Forbidden (insufficient permissions) |\r
| 404 | Not found |\r
| 429 | Rate limited |\r
| 500 | Server error |\r
\r
Error responses return:\r
\r
```json\r
{\r
  "error": {\r
    "code": 400,\r
    "message": "Invalid session ID format",\r
    "status": "INVALID_ARGUMENT"\r
  }\r
}\r
```\r
\r
## Notes\r
\r
- Get your API key from [jules.google.com/settings](https://jules.google.com/settings)\r
- Store it as the `JULES_API_KEY` environment variable\r
- Sources (repos) are connected via the Jules web UI at [jules.google](https://jules.google) — the API is read-only for sources\r
- Session resource names follow the pattern `sessions/{sessionId}`\r
- Activity resource names follow `sessions/{sessionId}/activities/{activityId}`\r
- All list endpoints support `pageSize` (1-100) and `pageToken` for pagination\r